kobako 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8298cb68a22a8100ea0ab330902a1d772049e990a35aa154b9233429f5c43b22
-  data.tar.gz: 9a1ae245d152dab877fc3104c157eab78a38fc15cbff3e94baf187eb955d4e35
+  metadata.gz: 1a1d65c175d931d915f6989a316d16cff80e6c4688f3510266f256f407175e14
+  data.tar.gz: 44a397aa2677edaa4541b6c69adfa1acc2ba05f8d7873ae4634f7c28074e01dd
 SHA512:
-  metadata.gz: 1aabea83fa046f0e5f9cc6ae3600e0f69cd045d38d3ecdcd91c6e71cbc19d29946ecd200ca44cc7941af329300d0f20a5733585a341e810ef19522fb083b4513
-  data.tar.gz: 23e5eccfa72eca1b6c39144c7d552a0eaf1a8467342fae504799744e8b4fee4036ad1d27a3e2311f0929cb300b74e04183ec9c8e3499043257860e9779c181ce
+  metadata.gz: 6e142164cfa46c2a12a7cfc1433a3a315a12eb5cc71a1d8ad4e6ae5a05d7b12eefec5e7b323ffd46e7917684e74ea732b8650785355f31bdb5a08ce27bf5545a
+  data.tar.gz: 16cf640810711eac6f3920f5678300b9c1b565118ff0da0d4fe02a6b1cc5be3a9394da69998ec0f2194b67d565306d933dafca9038a930aeabf7f5198435c533

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.17.0","wasm/kobako-core":"0.10.1","wasm/kobako-mruby":"0.10.1","wasm/kobako-io":"0.10.1","wasm/kobako-json":"0.10.1","wasm/kobako-regexp":"0.10.1","wasm/kobako-baker":"0.10.1","crates/kobako-codec":"0.10.1","crates/kobako-runtime":"0.10.1","crates/kobako-wasmtime":"0.10.1","crates/kobako":"0.10.1"}

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [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.17.0"
 dependencies = [
  "kobako-runtime",
  "kobako-wasmtime",
@@ -938,11 +938,11 @@ dependencies = [
 
 [[package]]
 name = "kobako-runtime"
-version = "0.10.0"
+version = "0.10.1"
 
 [[package]]
 name = "kobako-wasmtime"
-version = "0.10.0"
+version = "0.10.1"
 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`

data/crates/kobako-runtime/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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.1"
 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.1" # x-release-please-version
 ```
 
 ## License

data/crates/kobako-wasmtime/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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.1"
 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.1", 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.1" # 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.17.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.17.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.17.0
 platform: ruby
 authors:
 - Aotokitsuruya