kobako 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8298cb68a22a8100ea0ab330902a1d772049e990a35aa154b9233429f5c43b22
-  data.tar.gz: 9a1ae245d152dab877fc3104c157eab78a38fc15cbff3e94baf187eb955d4e35
+  metadata.gz: dcd0d1cd3ff81352a53d9ff9d716eda2f0a57194de86d178164be2ccadd15bee
+  data.tar.gz: 109c6b3d75f3a01e4b27463a3d9a7f6b9648fbef233d44fd026eb15336d58032
 SHA512:
-  metadata.gz: 1aabea83fa046f0e5f9cc6ae3600e0f69cd045d38d3ecdcd91c6e71cbc19d29946ecd200ca44cc7941af329300d0f20a5733585a341e810ef19522fb083b4513
-  data.tar.gz: 23e5eccfa72eca1b6c39144c7d552a0eaf1a8467342fae504799744e8b4fee4036ad1d27a3e2311f0929cb300b74e04183ec9c8e3499043257860e9779c181ce
+  metadata.gz: 8e9216cb7655f158b2d73b15d15f17ae334f69ca472f6e1c197f00a6630c2a7f2f54d211939bffe4f9f6ddba717f4688fea6be206fac6c0b2616a0f07cc9e470
+  data.tar.gz: d619788324d2d0dca679ab7c6510e5dae1819a378a8e24dc4cbaae111d3c66316077a9c510a07763a7bc0cfbdfa7375f8d3acf65e24cdd0b116b1a957927705e

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.16.0","wasm/kobako-core":"0.10.0","wasm/kobako-mruby":"0.10.0","wasm/kobako-io":"0.10.0","wasm/kobako-json":"0.10.0","wasm/kobako-regexp":"0.10.0","wasm/kobako-baker":"0.10.0","crates/kobako-codec":"0.10.0","crates/kobako-runtime":"0.10.0","crates/kobako-wasmtime":"0.10.0","crates/kobako":"0.10.0"}
+{".":"0.18.0","wasm/kobako-core":"0.10.2","wasm/kobako-mruby":"0.10.2","wasm/kobako-io":"0.10.2","wasm/kobako-json":"0.10.2","wasm/kobako-regexp":"0.10.2","wasm/kobako-baker":"0.10.2","crates/kobako-codec":"0.10.2","crates/kobako-runtime":"0.10.2","crates/kobako-wasmtime":"0.10.2","crates/kobako":"0.10.2"}

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [0.18.0](https://github.com/elct9620/kobako/compare/v0.17.0...v0.18.0) (2026-07-18)
+
+
+### Features
+
+* **bench:** add bench:all whole-round sweep ([6163cdf](https://github.com/elct9620/kobako/commit/6163cdffc6aa701a0306af40cc18121787b07e26))
+
+
+### Bug Fixes
+
+* **guest:** partition dispatch args by Ruby 3 call semantics (B-58) ([59a15a2](https://github.com/elct9620/kobako/commit/59a15a2d524b1ab902bc5e4a2763ffccb485e399))
+
+
+### Performance Improvements
+
+* **bench:** re-bless the anchor onto the codec-decomposition round ([74dca53](https://github.com/elct9620/kobako/commit/74dca5374a587242f8b1e00768dd33c330ff298c))
+
+## [0.17.0](https://github.com/elct9620/kobako/compare/v0.16.0...v0.17.0) (2026-07-17)
+
+
+### Features
+
+* **examples:** add vfs, an overlay filesystem that protects the disk ([1c83d44](https://github.com/elct9620/kobako/commit/1c83d44de971bf76d3db84cc3021b23bfc363842))
+* **tasks:** add a rake gate aggregate over every gate:* check ([c02e069](https://github.com/elct9620/kobako/commit/c02e06996134f124025538ba5c23f923606bc3d2))
+* **tasks:** add KobakoReport, the shared static-analysis output template ([7854a61](https://github.com/elct9620/kobako/commit/7854a61d30b823534bcad869a4e4970beab80340))
+* **tasks:** disclose the Ruby-only scope of the coverage report ([51cb291](https://github.com/elct9620/kobako/commit/51cb291bbc45671240a63e00a1461958694e4ee1))
+* **tasks:** disclose the tail below the hotspots top-N cut ([d7584ee](https://github.com/elct9620/kobako/commit/d7584ee610e347dcef9cb2515680c97c911320e5))
+* **tasks:** gate the pub-surface acknowledgement ledger for staleness ([5f97c77](https://github.com/elct9620/kobako/commit/5f97c773f300363e387ff8020523f141cdaaf88f))
+* **tasks:** gate the RBS collection lock against Gemfile.lock drift ([8201ce0](https://github.com/elct9620/kobako/commit/8201ce03848d9710239c586321a6ffb75de1950d))
+* **tasks:** measure Rust line coverage with cargo llvm-cov ([1f6bd9f](https://github.com/elct9620/kobako/commit/1f6bd9f2876f3ef6d8e60880c40198eb70327bf4))
+* **tasks:** open the stats reports with a self-describing banner ([914d0cf](https://github.com/elct9620/kobako/commit/914d0cf74e338a0a7405cc6f981135defac534f1))
+
+
+### Bug Fixes
+
+* **catalog:** match Extension dependencies by Symbol form ([57f17b8](https://github.com/elct9620/kobako/commit/57f17b872e506f3935ebd4ca1f9d81c4bc34455f))
+* **codec:** cap the host wrap-walk nesting depth (E-54) ([be67f37](https://github.com/elct9620/kobako/commit/be67f37108f24699354950f4e72293169da66917))
+* **codec:** keep the guard id out of the wire-symmetry inventory ([e51998b](https://github.com/elct9620/kobako/commit/e51998bc7d54715aecb58f3b7817c337cd882c8b))
+* **codec:** reject a non-representable #run argument Hash key cleanly ([dbabace](https://github.com/elct9620/kobako/commit/dbabaceecb6f32f37a26839b8162c0e94fe881bb))
+* **codec:** reject non-wire values via a factory guard, not to_msgpack ([8e5c6b8](https://github.com/elct9620/kobako/commit/8e5c6b8cb67faa2eb7b82d6e63e3f8464b1126a0))
+* **codec:** tighten map-decode pre-allocation to the true pair bound ([7094f91](https://github.com/elct9620/kobako/commit/7094f91898dae4c91c4e6863b09d25a6f34d096e))
+* **examples:** contain overlay writes and prove the vfs traversal guard ([2fe7965](https://github.com/elct9620/kobako/commit/2fe7965b8f588b160a907771a14e51f80cd8d3a7))
+* **examples:** contain vfs reads against symlink escape ([43317c8](https://github.com/elct9620/kobako/commit/43317c82c4a4171c08fdbf0c9fe7014cc249b926))
+* **guest:** reject non-representable dispatch args instead of to_s (E-55) ([6b9ab56](https://github.com/elct9620/kobako/commit/6b9ab562753407cf6168a5baad34140afd75a86a))
+* **tasks:** land the gate move for parity and wire:symmetry ([a0dddbc](https://github.com/elct9620/kobako/commit/a0dddbca9638418dbf3cd08e29806e05c5198cd3))
+* **tasks:** resync the pub-surface ledger to the renamed install cluster ([c6a6c33](https://github.com/elct9620/kobako/commit/c6a6c33f5802f4536a4ebcc2df36acc130059d89))
+
 ## [0.16.0](https://github.com/elct9620/kobako/compare/v0.15.0...v0.16.0) (2026-07-12)
 
 

data/Cargo.lock

@@ -929,7 +929,7 @@ dependencies = [
 
 [[package]]
 name = "kobako"
-version = "0.16.0"
+version = "0.18.0"
 dependencies = [
  "kobako-runtime",
  "kobako-wasmtime",
@@ -938,11 +938,11 @@ dependencies = [
 
 [[package]]
 name = "kobako-runtime"
-version = "0.10.0"
+version = "0.10.2"
 
 [[package]]
 name = "kobako-wasmtime"
-version = "0.10.0"
+version = "0.10.2"
 dependencies = [
  "kobako-runtime",
  "libc",

data/README.md

@@ -382,6 +382,34 @@ sandbox.run(:Greeter, name: "world") # => "hello, world"
 
 Use the source form for snippets authored in your repo; use the bytecode form when snippets ship as build artifacts from a separate `mrbc` pipeline. Both replay through the same per-invocation path, so no snippet content failure surfaces at `#preload` — force the first replay with a no-op invocation (e.g. `sandbox.eval("nil")`) when you want validation before real traffic.
 
+### Extensions
+
+An Extension teaches the guest a native-style constant by pairing a guest idiom (`source`) with an optional host `backend`. `Sandbox#install` composes the two through the existing `#preload` and `#bind` verbs, adding no wire or Guest Binary surface: pure operations run in-guest with no round-trip, while the rest dispatch to the backend under the same isolation and reflection guarantees as any bound Service ([`docs/extensions.md`](docs/extensions.md), [`docs/behavior/extension.md`](docs/behavior/extension.md) B-55..B-57).
+
+```ruby
+FILE = <<~'MRUBY'
+  class File < Kobako::Member
+    def self.basename(path) = path.split("/").last || ""  # pure: runs in-guest
+    # read / write are undefined here, so they dispatch to the backend
+  end
+MRUBY
+
+sandbox.install(
+  Kobako::Extension.new(
+    name: :File,
+    source: FILE,
+    backend: Kobako::Extension::Backend.new(
+      path: "File",
+      provider: -> { OverlayFileSystem.new(root) }  # callable → fresh per invocation
+    )
+  )
+)
+
+sandbox.eval('File.read("sample.txt")')  # dispatches to the backend's #read
+```
+
+The `backend.provider` sets the bound object's lifetime: a fixed object is shared across every invocation, while a callable is invoked once per invocation to yield a fresh object — the form a writable backend needs, so its state cannot leak across calls. kobako ships no concrete Extension; the idiom and backend are yours. The [overlay VFS example](examples/vfs/) is a worked `File` that reads through to disk while protecting it from guest writes.
+
 ## Security
 
 kobako isolates the guest, but **what it may reach is whatever you `bind`** — and `bind`
@@ -427,7 +455,7 @@ Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values
 
 The Cranelift JIT runs once per machine and gem version — the compiled artifact persists in a `.cwasm` disk cache, so later processes deserialize in milliseconds. An idle Sandbox holds no wasm instance (the canonical boot state is baked into the artifact and instantiated per invocation), which is why a thousand idle tenants cost ~33 MB total. `ext/` does not release the GVL during wasmtime execution, so wasm work is GVL-serialized: aggregate throughput stays around 17k `#eval`/s regardless of Thread count, though Ruby-side `#eval` setup still overlaps. A +10% regression on any of the six SPEC-mandated benchmarks blocks release.
 
-Regexp is an opt-in capability gem, excluded from the default binary and the gated set; its throughput is tracked in a separate non-gated characterization (`#10` in [`benchmark/README.md`](benchmark/README.md)). There `=~` (~5 µs/match) costs about 4× `match?` (~1.2 µs), because `=~` eagerly builds the `MatchData` and match globals — prefer `match?` for boolean tests.
+Regexp is an opt-in capability gem, excluded from the default binary and the gated set; its throughput is tracked in a separate non-gated characterization (`#11` in [`benchmark/README.md`](benchmark/README.md)). There `=~` (~5 µs/match) costs about 4× `match?` (~1.2 µs), because `=~` eagerly builds the `MatchData` and match globals — prefer `match?` for boolean tests.
 
 ```bash
 bundle exec rake bench  # six gated regression benchmarks (~5-8 min)

data/crates/kobako-runtime/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.10.2](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.10.1...kobako-runtime-v0.10.2) (2026-07-18)
+
+
+### Miscellaneous Chores
+
+* **kobako-runtime:** Synchronize kobako crates versions
+
+## [0.10.1](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.10.0...kobako-runtime-v0.10.1) (2026-07-17)
+
+
+### Miscellaneous Chores
+
+* **kobako-runtime:** Synchronize kobako crates versions
+
 ## [0.10.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.9.0...kobako-runtime-v0.10.0) (2026-07-12)
 
 

data/crates/kobako-runtime/Cargo.toml

@@ -13,7 +13,7 @@
 
 [package]
 name = "kobako-runtime"
-version = "0.10.0"
+version = "0.10.2"
 edition = "2021"
 description = "Engine-neutral host runtime contract for embedding kobako Wasm guests."
 license = "Apache-2.0"

data/crates/kobako-runtime/README.md

@@ -26,7 +26,7 @@ map the neutral types onto their own language surface.
 
 ```toml
 [dependencies]
-kobako-runtime = "0.10.0" # x-release-please-version
+kobako-runtime = "0.10.2" # x-release-please-version
 ```
 
 ## License

data/crates/kobako-wasmtime/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.10.2](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.10.1...kobako-wasmtime-v0.10.2) (2026-07-18)
+
+
+### Miscellaneous Chores
+
+* **kobako-wasmtime:** Synchronize kobako crates versions
+
+## [0.10.1](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.10.0...kobako-wasmtime-v0.10.1) (2026-07-17)
+
+
+### Miscellaneous Chores
+
+* **kobako-wasmtime:** Synchronize kobako crates versions
+
 ## [0.10.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.9.0...kobako-wasmtime-v0.10.0) (2026-07-12)
 
 

data/crates/kobako-wasmtime/Cargo.toml

@@ -15,7 +15,7 @@
 
 [package]
 name = "kobako-wasmtime"
-version = "0.10.0"
+version = "0.10.2"
 edition = "2021"
 description = "wasmtime implementation of the kobako host runtime contract."
 license = "Apache-2.0"
@@ -28,7 +28,7 @@ categories = ["wasm", "virtualization"]
 # The engine-neutral contract this crate implements. The version pin
 # rides the linked release group; the path keeps in-tree builds (and
 # the Ruby gem, which ships both crates) resolving locally.
-kobako-runtime = { version = "0.10.0", path = "../kobako-runtime" }
+kobako-runtime = { version = "0.10.2", path = "../kobako-runtime" }
 # wasmtime — host-side embedder for kobako.wasm. We disable default-features
 # and opt back in only what kobako needs: a Cranelift-backed runtime that can
 # compile a pre-built wasm32-wasip1 module on the host triple, plus the `wat`

data/crates/kobako-wasmtime/README.md

@@ -24,7 +24,7 @@ SDK consumes the same surface.
 
 ```toml
 [dependencies]
-kobako-wasmtime = "0.10.0" # x-release-please-version
+kobako-wasmtime = "0.10.2" # x-release-please-version
 ```
 
 ## License

data/crates/kobako-wasmtime/src/frames.rs

@@ -44,7 +44,7 @@ pub(crate) fn write_envelope(
     let memory = require_memory(exports)?;
 
     let ptr = alloc
-        .call(store.as_context_mut(), envelope.len() as u32)
+        .call(store.as_context_mut(), len_i32 as u32)
         .map_err(|e| Trap::Other(format!("failed to allocate input buffer: {e}")))?;
     if ptr == 0 {
         return Err(SetupError::Intact(

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.16.0"
+version = "0.18.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"

data/lib/kobako/catalog/extensions.rb

@@ -23,8 +23,11 @@ module Kobako
       # preloaded snippet, and — when it carries a +backend+ — reserve the
       # backend path in +services+. A callable provider reserves the path
       # with a placeholder the per-invocation refresh replaces; a fixed
-      # provider binds its object directly. Raises +ArgumentError+ on a
-      # malformed Extension; a malformed +name+ or +backend.path+ surfaces
+      # provider binds its object directly. Raises +ArgumentError+ for the two
+      # shapes +#validate!+ owns — +source+ not a String, or a present
+      # +backend+ that omits +path+ / +provider+. The Extension readers are
+      # duck-typed, so an object missing them surfaces the underlying
+      # +NoMethodError+, and a malformed +name+ or +backend.path+ surfaces
       # through the +snippets+ / +services+ registration it routes to.
       def install(extension, snippets:, services:)
         validate!(extension)
@@ -92,10 +95,10 @@ module Kobako
       end
 
       def assert_dependencies!
-        names = @entries.map(&:name)
+        names = @entries.map { |extension| symbolize(extension.name) }
         @entries.each do |extension|
           (extension.depends_on || []).each do |dependency|
-            next if names.include?(dependency)
+            next if names.include?(symbolize(dependency))
 
             raise ArgumentError,
                   "Extension #{extension.name.inspect} depends on #{dependency.inspect}, which is not installed"
@@ -103,6 +106,11 @@ module Kobako
         end
       end
 
+      # Match names and dependencies by Symbol so the Symbol-or-String forms
+      # of a constant token are interchangeable; a value that is neither
+      # falls through unchanged to the not-installed path.
+      def symbolize(name) = name.is_a?(String) ? name.to_sym : name
+
       def callable?(provider) = provider.respond_to?(:call)
 
       # A callable provider reserves its path with a placeholder that the

data/lib/kobako/codec/encoder.rb

@@ -22,15 +22,14 @@ module Kobako
     # themselves.
     module Encoder
       # Encode +value+ to wire bytes (binary-encoded String).
-      # Wire violations surface as +UnsupportedType+: SPEC's 12-entry type
-      # mapping is a closed set, and anything outside it is rejected by
-      # the msgpack gem itself (arbitrary objects raise +NoMethodError+
-      # from missing +to_msgpack+, integers outside i64..u64 raise
-      # +RangeError+). The +NoMethodError+ catch is deliberately broad:
-      # MessagePack signals "no wire representation" only through that error,
-      # so there is no narrower discriminator — a packer-internal
-      # +NoMethodError+ is likewise reported as +UnsupportedType+ rather than
-      # propagating.
+      # SPEC's 12-entry type mapping is a closed set: a value outside it is
+      # rejected as +UnsupportedType+ by the factory's +BasicObject+ guard
+      # (ExtTypes#register_unrepresentable), which raises before the msgpack
+      # gem can route the value through +to_msgpack+ — so a permissive
+      # +method_missing+ object cannot answer that probe and mis-encode. The
+      # rescue below maps the two violations the guard does not reach onto the
+      # same error: an integer outside i64..u64 (+RangeError+) and any
+      # packer-internal +NoMethodError+.
       def self.encode(value)
         FACTORY.dump(value)
       rescue ::RangeError, ::NoMethodError => e

data/lib/kobako/codec/ext_types.rb

@@ -33,18 +33,28 @@ module Kobako
       EXT_ERRENV = 0x02
       private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
 
+      # Inert ext id the unrepresentable-value guard registers under. It is
+      # never emitted (the guard's packer always raises) and never decoded
+      # (no unpacker is registered, so the id stays an UnknownExtTypeError on
+      # the wire), so it is not a wire ext type: deliberately not named
+      # +EXT_*+ like the three real ext codes, since it has no Rust-side mirror
+      # and must stay outside the wire-symmetry inventory.
+      UNREPRESENTABLE_GUARD_ID = 0x7F
+      private_constant :UNREPRESENTABLE_GUARD_ID
+
       module_function
 
-      # Assemble a +MessagePack::Factory+ with the three kobako ext types
-      # registered, frozen because registration is its only mutation and
-      # happens exactly once. The stateful conversions resolve their
-      # per-operation state at call time, so one registered factory serves
-      # every thread.
+      # Assemble a +MessagePack::Factory+ with the three kobako ext types plus
+      # the unrepresentable-value guard registered, frozen because
+      # registration is its only mutation and happens exactly once. The
+      # stateful conversions resolve their per-operation state at call time,
+      # so one registered factory serves every thread.
       def build_factory
         factory = MessagePack::Factory.new
         register_symbol(factory)
         register_handle(factory)
         register_fault(factory)
+        register_unrepresentable(factory)
         factory.freeze
       end
 
@@ -157,6 +167,26 @@ module Kobako
           unpacker: ->(payload) { ExtTypes.unpack_fault(payload, State.current) }
         )
       end
+
+      # A catch-all packer that rejects any value with no wire representation
+      # as +UnsupportedType+. Registered on +BasicObject+ so it also covers
+      # BasicObject-based proxies; the narrower Symbol / Handle / Fault
+      # registrations still win by most-specific match, and native types never
+      # reach it. Packer-only: the guard never writes bytes, so its id is inert
+      # and the decode surface stays fail-closed.
+      #
+      # This makes the host's non-wire detection a positive allowlist — a value
+      # outside the type set is rejected here rather than routed to +to_msgpack+
+      # — matching the guest's classname allowlist and the Rust codec's closed
+      # +Value+ enum. Without it, a value with a permissive +method_missing+
+      # answers the codec's +to_msgpack+ probe and mis-encodes as +nil+ instead
+      # of crossing as a Capability Handle.
+      def register_unrepresentable(factory)
+        factory.register_type(
+          UNREPRESENTABLE_GUARD_ID, BasicObject,
+          packer: ->(_value) { raise UnsupportedType, "value has no wire representation" }
+        )
+      end
     end
 
     # The process-wide registered factory: ext registration is paid once at

data/lib/kobako/codec/handle_walk.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../handle"
+require_relative "../errors"
 
 module Kobako
   module Codec
@@ -42,8 +43,16 @@ module Kobako
       # unsigned-64 union are rejected so the predicate agrees with the
       # msgpack gem's encode-time +RangeError+ behaviour the codec
       # already surfaces as UnsupportedType.
-      def representable?(value)
-        primitive_type?(value) || container_representable?(value)
+      #
+      # The optional +depth+ bounds the recursive descent at the wire's
+      # structural nesting cap so a self-referential container — reachable
+      # as a cyclic Hash key on the +#run+ argument path — reads as
+      # non-representable rather than looping, letting #deep_wrap_hash
+      # refuse it instead of overflowing this walk.
+      def representable?(value, depth = 0)
+        return false if depth > MAX_NESTING_DEPTH
+
+        primitive_type?(value) || container_representable?(value, depth)
       end
 
       # Deep-walk Array / Hash containers in +value+ and replace every
@@ -53,7 +62,11 @@ module Kobako
       # (Array, Hash) one structural level at a time; a non-representable
       # leaf is wrapped as-is without inspecting its internal structure.
       # An existing +Kobako::Handle+ is representable and passes through
-      # unchanged — auto-wrap never re-wraps a Handle.
+      # unchanged — auto-wrap never re-wraps a Handle. Only Hash *values*
+      # are wrapped: a Hash *key* must already be wire-representable, since a
+      # key is not auto-wrapped the way a value is — a non-representable key
+      # raises +Kobako::SandboxError+ rather than crossing as an opaque token
+      # the guest→host restore walk could not round-trip.
       #
       # +value+ may be any Ruby value; +handler+ must respond to
       # +#alloc(object) -> Kobako::Handle+ (a host-side
@@ -64,15 +77,46 @@ module Kobako
       # 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)
+      def deep_wrap(value, handler, depth = 0)
+        guard_nesting!(depth)
         case value
-        when ::Array then value.map { |element| HandleWalk.deep_wrap(element, handler) }
-        when ::Hash  then value.transform_values { |val| HandleWalk.deep_wrap(val, handler) }
+        when ::Array then value.map { |element| HandleWalk.deep_wrap(element, handler, depth + 1) }
+        when ::Hash  then HandleWalk.deep_wrap_hash(value, handler, depth)
         else
           representable?(value) ? value : handler.alloc(value)
         end
       end
 
+      # Refuse a wrap walk that has descended past the wire's structural
+      # nesting bound — a reference cycle necessarily trips it — so a +#run+
+      # argument fails as a clean +Kobako::SandboxError+ rather than an
+      # unbounded host recursion.
+      def guard_nesting!(depth)
+        return unless depth > MAX_NESTING_DEPTH
+
+        raise Kobako::SandboxError,
+              "a #run argument nests deeper than #{MAX_NESTING_DEPTH} levels and " \
+              "cannot cross the sandbox boundary (possible reference cycle)"
+      end
+
+      # Wrap a Hash on the host→guest argument path: each value's
+      # non-representable leaves become Handles, while each key must be
+      # wire-representable as-is. A stateful object may cross the boundary as
+      # a Hash value but not as a key — the one deliberate asymmetry with the
+      # guest→host restore walk, which resolves Handle keys the guest built.
+      def deep_wrap_hash(hash, handler, depth)
+        wrapped = {} # : Hash[untyped, untyped]
+        hash.each do |key, val|
+          unless HandleWalk.representable?(key, depth + 1)
+            raise Kobako::SandboxError,
+                  "a Hash passed to #run has a key that cannot cross the sandbox boundary " \
+                  "(#{key.class}); only wire-representable values may be Hash keys"
+          end
+          wrapped[key] = HandleWalk.deep_wrap(val, handler, depth + 1)
+        end
+        wrapped
+      end
+
       # 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
@@ -118,10 +162,10 @@ module Kobako
       # elements and Hash key+value pairs through the public
       # #representable?. Not part of the public surface; reach for
       # #representable? instead.
-      def container_representable?(value)
+      def container_representable?(value, depth)
         case value
-        when ::Array then value.all? { |element| HandleWalk.representable?(element) }
-        when ::Hash  then value.all? { |key, val| HandleWalk.representable?(key) && HandleWalk.representable?(val) }
+        when ::Array then value.all? { |element| HandleWalk.representable?(element, depth + 1) }
+        when ::Hash  then value.all? { |pair| pair.all? { |member| HandleWalk.representable?(member, depth + 1) } }
         else false
         end
       end

data/lib/kobako/codec.rb

@@ -28,6 +28,12 @@ module Kobako
   # alongside +codec::EXT_SYMBOL+ / +codec::EXT_HANDLE+ /
   # +codec::EXT_ERRENV+ on that side.
   module Codec
+    # The maximum structural nesting depth the wire represents (the
+    # MessagePack ecosystem's bound), shared with the guest +kobako_codec+
+    # so both sides cap identically. The host→guest wrap walk refuses a
+    # +#run+ argument nesting past it — a reference cycle necessarily does.
+    MAX_NESTING_DEPTH = 128
+
     # Bracket a decode and return the block's result together with whether
     # the decoded tree carried an ext 0x01 Capability Handle — the signal a
     # dispatch path uses to skip an all-identity Handle-resolution walk.

data/lib/kobako/extension.rb

@@ -34,7 +34,9 @@ module Kobako
     # invocation to yield that invocation's object, so a fresh object backs
     # the path every invocation. Callability is the sole discriminator — a
     # fixed backend that is itself callable is supplied through a
-    # non-callable wrapper.
+    # non-callable wrapper. A callable provider that raises propagates its
+    # exception to the invocation caller and leaves the guest unrun; the
+    # next invocation resolves it afresh.
     class Backend < Data.define(:path, :provider)
     end
 

data/lib/kobako/transport/dispatcher.rb

@@ -87,6 +87,11 @@ module Kobako
         args, kwargs = resolve_call_args(request, handler, carried_handle)
         yielder = Yielder.new(yield_to_guest, BREAK_THROW, handler) if request.block_given
         encode_ok(catch(BREAK_THROW) { invoke(target, request.method_name, args, kwargs, yielder) }, handler)
+      # StandardError is the boundary by intent: a Service method's
+      # application fault folds into a guest-rescuable Response.error, while a
+      # host-process failure (NoMemoryError, SignalException, a bare Exception)
+      # stays uncaught and traps the invocation rather than being masked as a
+      # rescuable fault.
       rescue StandardError => e
         encode_caught_error(e)
       ensure

data/lib/kobako/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kobako
-  VERSION = "0.16.0"
+  VERSION = "0.18.0"
 end

data/sig/kobako/catalog/extensions.rbs

@@ -17,6 +17,8 @@ module Kobako
 
       def assert_dependencies!: () -> void
 
+      def symbolize: (untyped name) -> untyped
+
       def callable?: (untyped provider) -> bool
 
       def initial_object: (untyped provider) -> untyped

data/sig/kobako/codec/ext_types.rbs

@@ -4,6 +4,7 @@ module Kobako
       EXT_SYMBOL: Integer
       EXT_HANDLE: Integer
       EXT_ERRENV: Integer
+      UNREPRESENTABLE_GUARD_ID: Integer
 
       def self?.build_factory: () -> MessagePack::Factory
 
@@ -24,6 +25,8 @@ module Kobako
       def self?.register_handle: (MessagePack::Factory factory) -> void
 
       def self?.register_fault: (MessagePack::Factory factory) -> void
+
+      def self?.register_unrepresentable: (MessagePack::Factory factory) -> void
     end
 
     FACTORY: MessagePack::Factory

data/sig/kobako/codec/handle_walk.rbs

@@ -3,15 +3,19 @@ module Kobako
     module HandleWalk
       MSGPACK_INT_RANGE: Range[Integer]
 
-      def self?.representable?: (untyped value) -> bool
+      def self?.representable?: (untyped value, ?Integer depth) -> bool
 
-      def self?.deep_wrap: (untyped value, Kobako::Codec::_HandleTable handler) -> untyped
+      def self?.deep_wrap: (untyped value, Kobako::Codec::_HandleTable handler, ?Integer depth) -> untyped
+
+      def self?.guard_nesting!: (Integer depth) -> void
+
+      def self?.deep_wrap_hash: (Hash[untyped, untyped] hash, Kobako::Codec::_HandleTable handler, Integer depth) -> Hash[untyped, untyped]
 
       def self?.deep_restore: (untyped value, Kobako::Codec::_HandleTable handler) -> untyped
 
       def self?.primitive_type?: (untyped value) -> bool
 
-      def self?.container_representable?: (untyped value) -> bool
+      def self?.container_representable?: (untyped value, Integer depth) -> bool
     end
   end
 end

data/sig/kobako/codec.rbs

@@ -1,5 +1,17 @@
 module Kobako
   module Codec
+    MAX_NESTING_DEPTH: Integer
+
+    # A value in the closed wire type set (docs/wire-codec.md § Type
+    # Mapping): the scalar leaves, a Capability Handle, and Array / Hash
+    # containers of the same. The by-value payloads that cross the wire —
+    # dispatch arguments and success values — inhabit this type; a Fault
+    # (ext 0x02) is an envelope-position value, not a wire_value.
+    type wire_value = nil | bool | Integer | Float | String | Symbol
+                    | Kobako::Handle
+                    | Array[wire_value]
+                    | Hash[wire_value, wire_value]
+
     def self.track_handles: [T] { () -> T } -> [T, bool]
     def self.forbid_faults: [T] { () -> T } -> T
 

data/sig/kobako/outcome.rbs

@@ -9,7 +9,7 @@ module Kobako
 
     def self?.split_tag: (String bytes) -> [Integer?, String]
 
-    def self?.decode_value: (String body) -> untyped
+    def self?.decode_value: (String body) -> Kobako::Codec::wire_value
 
     def self?.decode_panic: (String body) -> void
 

data/sig/kobako/transport/request.rbs

@@ -3,19 +3,19 @@ module Kobako
     class Request < Data
       attr_reader target: String | Kobako::Handle
       attr_reader method_name: String
-      attr_reader args: Array[untyped]
-      attr_reader kwargs: Hash[Symbol, untyped]
+      attr_reader args: Array[Kobako::Codec::wire_value]
+      attr_reader kwargs: Hash[Symbol, Kobako::Codec::wire_value]
       attr_reader block_given: bool
 
-      def self.new: (target: String | Kobako::Handle, method_name: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped], ?block_given: bool) -> Request
+      def self.new: (target: String | Kobako::Handle, method_name: String, ?args: Array[Kobako::Codec::wire_value], ?kwargs: Hash[Symbol, Kobako::Codec::wire_value], ?block_given: bool) -> Request
 
       def self.decode: (String bytes) -> Request
 
-      def initialize: (target: String | Kobako::Handle, method_name: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped], ?block_given: bool) -> void
+      def initialize: (target: String | Kobako::Handle, method_name: String, ?args: Array[Kobako::Codec::wire_value], ?kwargs: Hash[Symbol, Kobako::Codec::wire_value], ?block_given: bool) -> void
 
       def encode: () -> String
 
-      def with: (?target: String | Kobako::Handle, ?method_name: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped], ?block_given: bool) -> Request
+      def with: (?target: String | Kobako::Handle, ?method_name: String, ?args: Array[Kobako::Codec::wire_value], ?kwargs: Hash[Symbol, Kobako::Codec::wire_value], ?block_given: bool) -> Request
 
       def ==: (untyped other) -> bool
 

data/sig/kobako/transport/response.rbs

@@ -5,7 +5,7 @@ module Kobako
 
     class Response < Data
       attr_reader status: Integer
-      attr_reader payload: untyped
+      attr_reader payload: Kobako::Codec::wire_value | Kobako::Fault
 
       def self.ok: (untyped value) -> Response
 

data/sig/kobako/transport/run.rbs

@@ -4,8 +4,8 @@ module Kobako
       NAME_PATTERN: Regexp
 
       attr_reader entrypoint: Symbol
-      attr_reader args: Array[untyped]
-      attr_reader kwargs: Hash[Symbol, untyped]
+      attr_reader args: Array[Kobako::Codec::wire_value]
+      attr_reader kwargs: Hash[Symbol, Kobako::Codec::wire_value]
 
       def self.new: (entrypoint: Symbol | String, ?args: Array[untyped], ?kwargs: Hash[untyped, untyped]) -> Run
 

data/sig/kobako/transport/yield.rbs

@@ -8,7 +8,7 @@ module Kobako
 
     class Yield
       attr_reader tag: Integer
-      attr_reader value: untyped
+      attr_reader value: Kobako::Codec::wire_value | Kobako::Fault
 
       def self.decode: (String bytes) -> Yield
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Aotokitsuruya