kobako 0.15.0-aarch64-linux → 0.17.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00df75af1fd85b3c4d3729d456148a282ab904f26162e6930ecd8ad003bcd9df
-  data.tar.gz: 34533660556ce44eddbc76831b973ed10217e5a3801affbb5b7a991e15069c3a
+  metadata.gz: a6a999cf44d11a6c9456e2eb64469cad4f3e2171a0b36fe50f6a521af92f054d
+  data.tar.gz: e9815939407b3c49b4bdca283d9389e6aeeca3394e4028a2e30032f9bd299d8c
 SHA512:
-  metadata.gz: 34250f5db8642efbab2654993df69316be3cdb581bafacc07ac6993e072ea5addf3c04bae86d41ad5412c182b3f22e9aa158b9e9cb27d86571a7cf01ad38a674
-  data.tar.gz: ac5d4d68b447714f78412acd554c842cbd52f8bfab46794ffa7fabe1dcc6a169bb4d04a3caf10e88bf16ff41b4312ab30626687ee46b31530514b5fa4ac93242
+  metadata.gz: 4464cad4dd28d5b6db8eed691ce623a28a0fb18eb1d6486ed5e8fc918f6ef0be125cc9e089475557aa5f298b488d5436b3f5f716e9d92b9d4e74cf2013d91117
+  data.tar.gz: 7d582dc78e56ec880cda51f76561371a72b7a44a63f11699436e12f3baadd4d8f756e376d31a1826bace9534b79741ddedea5090da8e1848d6c2db157c7c4a61

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.15.0","wasm/kobako-core":"0.9.0","wasm/kobako-mruby":"0.9.0","wasm/kobako-io":"0.9.0","wasm/kobako-json":"0.9.0","wasm/kobako-regexp":"0.9.0","wasm/kobako-baker":"0.9.0","crates/kobako-codec":"0.9.0","crates/kobako-runtime":"0.9.0","crates/kobako-wasmtime":"0.9.0","crates/kobako":"0.9.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,51 @@
 # 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)
+
+
+### Features
+
+* **sandbox:** add the Extension install mechanism ([ad8e4da](https://github.com/elct9620/kobako/commit/ad8e4da703e4ceee85959663d77bb1e26c26791a))
+* **sdk:** add the Extension install mechanism to the Rust host SDK ([4043f76](https://github.com/elct9620/kobako/commit/4043f764b7038619a30c16542ed38d566e4a72a9))
+* **tasks:** break each module down by language in stats:<slug> ([b496e3c](https://github.com/elct9620/kobako/commit/b496e3cb23150f8f073cc1b972978cfbebfbb1e6))
+* **tasks:** report code sizes per publishable module in stats:all ([f554930](https://github.com/elct9620/kobako/commit/f554930e669a82bed0c7305c5cbbab96c3ae79da))
+* **tasks:** split impl vs inline test per module in stats:all ([cefa38d](https://github.com/elct9620/kobako/commit/cefa38d96ff79509b947269ea5c361ead0610bfa))
+
+
+### Bug Fixes
+
+* **tasks:** count Rust inline tests in the stats code-to-test ratio ([134c970](https://github.com/elct9620/kobako/commit/134c9704a5a9bb6fb01c1aa7968f907d1436e5f2))
+
 ## [0.15.0](https://github.com/elct9620/kobako/compare/v0.14.0...v0.15.0) (2026-07-11)
 
 

data/README.md

@@ -69,7 +69,7 @@ The host embeds the sandbox and owns the SPEC wire codec. Choose by your host la
 | Frontend | Package | Add it | Best for |
 |----------|---------|--------|----------|
 | Ruby gem | `kobako` (RubyGems) | `gem install kobako` | A Ruby host — Services, Handles, snippets, and pooling out of the box |
-| Rust SDK | `kobako` (crates.io) | `kobako = "0.8"` | A Rust host — the same behavior contract behind an idiomatic Rust API |
+| Rust SDK | `kobako` (crates.io) | `kobako = "0.9"` | A Rust host — the same behavior contract behind an idiomatic Rust API |
 | Low-level crates | `kobako-wasmtime` + `kobako-runtime` + `kobako-codec` | Cargo deps | A custom host, or driving the wire directly in another language |
 
 The Rust crates are documented on [crates.io](https://crates.io/crates/kobako); the Ruby gem is this README. Two runnable Rust hosts show the choice: [`plugin-rs`](examples/plugin-rs) builds on the SDK, and [`wire-rs`](examples/wire-rs) assembles a host by hand on the low-level crates.
@@ -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,19 @@
 # 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)
+
+
+### Miscellaneous Chores
+
+* **kobako-runtime:** Synchronize kobako crates versions
+
 ## [0.9.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.8.0...kobako-runtime-v0.9.0) (2026-07-11)
 
 

data/crates/kobako-runtime/README.md

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

data/crates/kobako-wasmtime/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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)
+
+
+### Miscellaneous Chores
+
+* **kobako-wasmtime:** Synchronize kobako crates versions
+
 ## [0.9.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.8.0...kobako-wasmtime-v0.9.0) (2026-07-11)
 
 

data/crates/kobako-wasmtime/README.md

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

data/lib/kobako/catalog/extensions.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Catalog
+    # Kobako::Catalog::Extensions — per-Sandbox registry of installed
+    # Extensions. Composes each Extension onto the sibling registries at
+    # install time (its +source+ into +Catalog::Snippets+, its +backend+
+    # path into +Catalog::Services+), asserts declared dependencies are
+    # present when the Sandbox seals, and resolves each callable-backed
+    # path to a fresh object at the start of every invocation.
+    #
+    # Sealing and the reject-after-install guard are governed by the owning
+    # Sandbox through +Catalog::Services#sealed?+, the shared seal signal;
+    # this registry only records entries and enforces the Extension-shape
+    # and dependency rules.
+    class Extensions
+      def initialize
+        @entries = [] # : Array[untyped]
+        @asserted = false
+      end
+
+      # Install +extension+: validate its shape, register its +source+ as a
+      # 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+ 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)
+        snippets.register(code: extension.source, name: extension.name)
+        backend = extension.backend
+        services.bind(backend.path, initial_object(backend.provider)) if backend
+        @entries << extension
+        self
+      end
+
+      # Assert every installed Extension's +depends_on+ names a fellow
+      # installed Extension. Runs once, when the Sandbox first seals; an
+      # unmet dependency raises +ArgumentError+ naming the gap, before the
+      # guest runs. Idempotent across later invocations.
+      def seal!
+        return self if @asserted
+
+        @asserted = true
+        assert_dependencies!
+        self
+      end
+
+      # Resolve each callable-backed path to this invocation's object and
+      # refresh it behind its already-sealed path in +services+. Distinct
+      # providers yield distinct objects; one provider shared by several
+      # Extensions is invoked once and its result shared, so provider
+      # identity is resource identity. Fixed providers are left untouched —
+      # they stay the object bound at install.
+      def refresh_backends!(services)
+        resolved = {} # : Hash[untyped, untyped]
+        resolved.compare_by_identity
+        @entries.each { |extension| refresh_backend(extension, services, resolved) }
+        self
+      end
+
+      private
+
+      # Resolve one Extension's callable-backed path against the shared
+      # per-invocation +resolved+ cache (keyed by provider identity) and
+      # refresh it in +services+. A fixed provider is skipped — its object
+      # stays as bound at install.
+      def refresh_backend(extension, services, resolved)
+        backend = extension.backend
+        return unless backend
+
+        provider = backend.provider
+        return unless callable?(provider)
+
+        object = resolved.fetch(provider) { resolved[provider] = provider.call }
+        services.refresh(backend.path, object)
+      end
+
+      # Enforce the Extension-shape checks +#preload+ / +#bind+ do not: a
+      # mandatory String +source+ (the install/bind boundary) and a
+      # +backend+ that, when present, exposes +path+ and +provider+.
+      def validate!(extension)
+        source = extension.source
+        raise ArgumentError, "Extension #source must be a String, got #{source.class}" unless source.is_a?(String)
+
+        backend = extension.backend
+        return if backend.nil?
+        return if backend.respond_to?(:path) && backend.respond_to?(:provider)
+
+        raise ArgumentError, "Extension #backend must expose #path and #provider"
+      end
+
+      def assert_dependencies!
+        names = @entries.map { |extension| symbolize(extension.name) }
+        @entries.each do |extension|
+          (extension.depends_on || []).each do |dependency|
+            next if names.include?(symbolize(dependency))
+
+            raise ArgumentError,
+                  "Extension #{extension.name.inspect} depends on #{dependency.inspect}, which is not installed"
+          end
+        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
+      # per-invocation refresh replaces before any dispatch; a fixed
+      # provider is the bound object itself.
+      def initial_object(provider) = callable?(provider) ? nil : provider
+    end
+  end
+end

data/lib/kobako/catalog/services.rb

@@ -65,6 +65,18 @@ module Kobako
         @bindings[target_str]
       end
 
+      # Replace the object bound at an already-registered +path+ without the
+      # collision or seal checks +#bind+ applies. +Catalog::Extensions+ calls
+      # this during +begin_invocation!+ to swap a callable backend provider's
+      # per-invocation result behind a path whose Frame 1 membership was
+      # fixed at the seal. A path that was never registered is left untouched,
+      # so the sealed key set can never grow here.
+      def refresh(path, object)
+        key = path.to_s
+        @bindings[key] = object if @bindings.key?(key)
+        self
+      end
+
       # Encode the preamble as msgpack bytes for stdin Frame 1 delivery —
       # a flat array of the bound constant paths, in bind order:
       # +["MyService::KV", "File"]+. Routes through Kobako::Codec::Encoder

data/lib/kobako/catalog.rb

@@ -3,13 +3,15 @@
 require_relative "catalog/handles"
 require_relative "catalog/services"
 require_relative "catalog/snippets"
+require_relative "catalog/extensions"
 
 module Kobako
   # Kobako::Catalog — Sandbox-level configuration and per-invocation
-  # allocation tables. Houses the three host-side registries the Sandbox
-  # owns: +Catalog::Services+ (path→Service binding registry),
-  # +Catalog::Snippets+ (preloaded source / bytecode entries), and
-  # +Catalog::Handles+ (per-invocation Handle ID allocator).
+  # allocation tables. Houses the host-side registries the Sandbox owns:
+  # +Catalog::Services+ (path→Service binding registry),
+  # +Catalog::Snippets+ (preloaded source / bytecode entries),
+  # +Catalog::Extensions+ (installed Extensions, composed onto Services /
+  # Snippets), and +Catalog::Handles+ (per-invocation Handle ID allocator).
   #
   # See {SPEC.md Refinement → Internal Concepts}[link:../../SPEC.md] for
   # how Catalog fits alongside Transport and Runtime.

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Kobako::Extension — a guest idiom paired with an optional host backend,
+  # installed on a Sandbox via +Sandbox#install+. It composes the existing
+  # +#preload+ (the guest +source+) and +#bind+ (the +backend+) verbs into
+  # one setup unit, so guest code sees a native-style constant whose pure
+  # methods run in-guest and whose privileged methods dispatch to the
+  # backend.
+  #
+  # The four readers form the contract +#install+ duck-types on:
+  #
+  #   * +name+ — a Symbol matching +/\A[A-Z]\w*\z/+, the preloaded snippet's
+  #     canonical backtrace name and the +depends_on+ match key. Independent
+  #     of any bound path.
+  #   * +source+ — the mruby idiom as a String; always present, since an
+  #     Extension always carries a guest idiom. A host object with no idiom
+  #     is bound with +#bind+ directly.
+  #   * +backend+ — an +Extension::Backend+ or +nil+ for a pure-guest
+  #     Extension.
+  #   * +depends_on+ — Symbol names of Extensions that must also be
+  #     installed, checked for presence at the first invocation.
+  #
+  # +Kobako::Extension+ is the bundled value type; any object exposing the
+  # four readers is equally valid, so a Host App or gem may supply its own.
+  class Extension < Data.define(:name, :source, :backend, :depends_on)
+    # Kobako::Extension::Backend — the host attachment of an Extension,
+    # pairing +path+ (the constant path the backend binds at, single-segment
+    # +"File"+ or nested +"MyApp::Store"+, spelling the guest constant the
+    # idiom routes to) with +provider+ (the source of the bound object).
+    #
+    # A +provider+ that is not itself callable is the bound object, resolved
+    # once for the Sandbox's life; a callable provider is invoked once per
+    # 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. 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
+
+    # +backend+ and +depends_on+ default to absent so the common
+    # pure-idiom and single-backend shapes stay terse.
+    def initialize(name:, source:, backend: nil, depends_on: [])
+      super
+    end
+  end
+end

data/lib/kobako/sandbox.rb

@@ -48,29 +48,21 @@ module Kobako
     # so use +#stdout_truncated?+ to observe overflow. Populated on every
     # outcome — including a rescued +TrapError+, after which it holds the
     # bytes written before the trap fired — mirroring +#usage+.
-    def stdout
-      @stdout_capture.bytes
-    end
+    def stdout = @stdout_capture.bytes
 
     # Returns the bytes the guest wrote to stderr during the most recent
     # invocation as a UTF-8 String, clipped at +stderr_limit+. Empty before
     # any invocation. Mirror of +#stdout+.
-    def stderr
-      @stderr_capture.bytes
-    end
+    def stderr = @stderr_capture.bytes
 
     # Returns +true+ iff stdout capture during the most recent invocation
     # exceeded +stdout_limit+. Resets to +false+ at the start of the next
     # invocation.
-    def stdout_truncated?
-      @stdout_capture.truncated?
-    end
+    def stdout_truncated? = @stdout_capture.truncated?
 
     # Returns +true+ iff stderr capture during the most recent invocation
     # exceeded +stderr_limit+. Mirror of +#stdout_truncated?+.
-    def stderr_truncated?
-      @stderr_capture.truncated?
-    end
+    def stderr_truncated? = @stderr_capture.truncated?
 
     # Returns the +Kobako::Usage+ value object for the most recent
     # invocation. Carries +wall_time+ (Float seconds the guest export call spent
@@ -102,6 +94,7 @@ module Kobako
       @handler = Catalog::Handles.new
       @services = Kobako::Catalog::Services.new(handler: @handler)
       @snippets = Catalog::Snippets.new
+      @extensions = Catalog::Extensions.new
       @runtime = build_runtime!
       install_dispatch_proc!
       reset_invocation_state!
@@ -121,6 +114,22 @@ module Kobako
       self
     end
 
+    # Install one or more Extensions — each a guest idiom (+source+) paired
+    # with an optional host +backend+, composed onto the Sandbox through
+    # +#preload+ and +#bind+. An Extension is any object exposing
+    # +name+ / +source+ / +backend+ / +depends_on+; +Kobako::Extension+ is
+    # the bundled value type. Returns +self+.
+    #
+    # Raises +ArgumentError+ for a malformed Extension, a call after the
+    # first invocation seals registration, or — at that first invocation —
+    # an unmet +depends_on+.
+    def install(*extensions)
+      raise ArgumentError, "cannot install after first Sandbox invocation" if @services.sealed?
+
+      extensions.each { |extension| @extensions.install(extension, snippets: @snippets, services: @services) }
+      self
+    end
+
     # Register a snippet on this Sandbox in one of two forms:
     #
     #   * +preload(code: source, name: Name)+ — +source+ is mruby source
@@ -241,14 +250,18 @@ module Kobako
       end
     end
 
-    # Per-invocation prologue. Seals the Service / snippet registries on
-    # first call (idempotent) and zeros the per-invocation capability
+    # Per-invocation prologue. Seals the Service / snippet / Extension
+    # registries on first call (idempotent — asserting Extension
+    # dependencies then), refreshes each callable Extension backend to this
+    # invocation's fresh object, and zeros the per-invocation capability
     # state — capture buffers, truncation predicates, and the
     # +Catalog::Handles+ counter — before the guest runs. The
     # +Catalog::Handles+ itself is held as +@handler+ and never exposed
     # beyond this class — it is not part of the Host App's surface.
     def begin_invocation!
       @services.seal!
+      @extensions.seal!
+      @extensions.refresh_backends!(@services)
       @handler.reset!
       reset_invocation_state!
     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.15.0"
+  VERSION = "0.17.0"
 end

data/lib/kobako.rb

@@ -10,6 +10,7 @@ rescue LoadError
 end
 
 require_relative "kobako/errors"
+require_relative "kobako/extension"
 require_relative "kobako/transport"
 require_relative "kobako/catalog"
 require_relative "kobako/runtime"

data/sig/kobako/catalog/extensions.rbs

@@ -0,0 +1,27 @@
+module Kobako
+  module Catalog
+    class Extensions
+      def initialize: () -> void
+
+      def install: (untyped extension, snippets: Kobako::Catalog::Snippets, services: Kobako::Catalog::Services) -> self
+
+      def seal!: () -> self
+
+      def refresh_backends!: (Kobako::Catalog::Services services) -> self
+
+      private
+
+      def refresh_backend: (untyped extension, Kobako::Catalog::Services services, Hash[untyped, untyped] resolved) -> void
+
+      def validate!: (untyped extension) -> void
+
+      def assert_dependencies!: () -> void
+
+      def symbolize: (untyped name) -> untyped
+
+      def callable?: (untyped provider) -> bool
+
+      def initial_object: (untyped provider) -> untyped
+    end
+  end
+end

data/sig/kobako/catalog/services.rbs

@@ -9,6 +9,8 @@ module Kobako
 
       def lookup: (Symbol | String target) -> untyped
 
+      def refresh: (Symbol | String path, untyped object) -> self
+
       def encode: () -> String
 
       def seal!: () -> self

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/extension.rbs

@@ -0,0 +1,20 @@
+module Kobako
+  class Extension < Data
+    attr_reader name: Symbol
+    attr_reader source: String
+    attr_reader backend: Kobako::Extension::Backend?
+    attr_reader depends_on: Array[Symbol]
+
+    def self.new: (name: Symbol, source: String, ?backend: Kobako::Extension::Backend?, ?depends_on: Array[Symbol]) -> Kobako::Extension
+
+    def initialize: (name: Symbol, source: String, ?backend: Kobako::Extension::Backend?, ?depends_on: Array[Symbol]) -> void
+
+    class Backend < Data
+      attr_reader path: String
+      attr_reader provider: untyped
+
+      def self.new: (path: String, provider: untyped) -> Kobako::Extension::Backend
+                  | (String path, untyped provider) -> Kobako::Extension::Backend
+    end
+  end
+end

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/sandbox.rbs

@@ -31,6 +31,8 @@ module Kobako
 
     def bind: (Symbol | String path, untyped object) -> Kobako::Sandbox
 
+    def install: (*untyped extensions) -> Kobako::Sandbox
+
     def preload: (code: String, name: Symbol | String) -> Kobako::Sandbox
                | (binary: String) -> Kobako::Sandbox
 

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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: aarch64-linux
 authors:
 - Aotokitsuruya
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-07-11 00:00:00.000000000 Z
+date: 2026-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: msgpack
@@ -50,6 +50,7 @@ files:
 - lib/kobako/4.0/kobako.so
 - lib/kobako/capture.rb
 - lib/kobako/catalog.rb
+- lib/kobako/catalog/extensions.rb
 - lib/kobako/catalog/handles.rb
 - lib/kobako/catalog/services.rb
 - lib/kobako/catalog/snippets.rb
@@ -62,6 +63,7 @@ files:
 - lib/kobako/codec/state.rb
 - lib/kobako/codec/utils.rb
 - lib/kobako/errors.rb
+- lib/kobako/extension.rb
 - lib/kobako/fault.rb
 - lib/kobako/handle.rb
 - lib/kobako/outcome.rb
@@ -88,6 +90,7 @@ files:
 - sig/kobako.rbs
 - sig/kobako/capture.rbs
 - sig/kobako/catalog.rbs
+- sig/kobako/catalog/extensions.rbs
 - sig/kobako/catalog/handles.rbs
 - sig/kobako/catalog/services.rbs
 - sig/kobako/catalog/snippets.rbs
@@ -100,6 +103,7 @@ files:
 - sig/kobako/codec/state.rbs
 - sig/kobako/codec/utils.rbs
 - sig/kobako/errors.rbs
+- sig/kobako/extension.rbs
 - sig/kobako/fault.rbs
 - sig/kobako/handle.rbs
 - sig/kobako/outcome.rbs