kobako 0.9.2-aarch64-linux → 0.11.0-aarch64-linux

data/lib/kobako/transport/run.rb

@@ -9,26 +9,24 @@ module Kobako
   # consumed by +__kobako_run+.
   module Transport
     # Host-side value object for a single +Sandbox#run+ invocation
-    # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md];
-    # {docs/behavior.md B-31}[link:../../../docs/behavior.md]).
+    # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
     #
     # A Run captures the host-layer concept of "a single +#run+
     # call": the entrypoint constant name plus its positional and keyword
-    # arguments. Host pre-flight (E-24 / E-25 / E-29 / E-30) is enforced at
-    # construction so the Value Object is the single source of truth —
-    # anything that passes +Run.new+ is safe to encode and ship to
-    # the guest.
+    # arguments. Host pre-flight (entrypoint type / name pattern, forged
+    # Handle, kwargs-key type) is enforced at construction so the Value
+    # Object is the single source of truth — anything that passes
+    # +Run.new+ is safe to encode and ship to the guest.
     #
     # Run is the host→guest entrypoint dispatch envelope (the +#run+
     # request shape), the symmetric counterpart to the guest→host
     # +Request+ envelope. +#encode+ takes the Sandbox's
     # +Catalog::Handles+ and routes any non-wire-representable +args+ /
-    # +kwargs+ leaf through it as a +Kobako::Handle+
-    # ({docs/behavior.md B-34}[link:../../../docs/behavior.md]) — the
+    # +kwargs+ leaf through it as a +Kobako::Handle+ — the
     # symmetric counterpart of the guest→host wrap path in the
-    # dispatcher (B-14). A +Kobako::Handle+ that arrives **already
+    # dispatcher. A +Kobako::Handle+ that arrives **already
     # constructed** in the caller's +args+ / +kwargs+ is rejected at
-    # construction (E-29): legitimate Handles only enter Host App code
+    # construction: legitimate Handles only enter Host App code
     # through error fields, so a Handle reaching the call site is by
     # definition smuggled in. The +#encode+ output is the "Run envelope"
     # that ships through the +__kobako_run+ command buffer.
@@ -36,8 +34,8 @@ module Kobako
     # Built on the +class X < Data.define(...)+ subclass form (the
     # Steep-friendly shape — see +lib/kobako/outcome/panic.rb+).
     class Run < Data.define(:entrypoint, :args, :kwargs)
-      # Ruby constant-name pattern enforced on the +entrypoint+ Symbol
-      # ({docs/behavior.md E-25}[link:../../../docs/behavior.md]). Parallel to
+      # Ruby constant-name pattern enforced on the +entrypoint+ Symbol.
+      # Parallel to
       # +Kobako::Catalog::Snippets::NAME_PATTERN+; the two constants name the
       # same regex but cover distinct surfaces (snippet identity vs.
       # entrypoint resolution) so a future divergence stays local.
@@ -55,10 +53,9 @@ module Kobako
       # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
       # Walks +args+ / +kwargs+ through {Codec::Utils.deep_wrap} so any
       # non-wire-representable leaf is allocated into +handler+ and
-      # replaced with a +Kobako::Handle+
-      # ({docs/behavior.md B-34}[link:../../../docs/behavior.md]); the
+      # replaced with a +Kobako::Handle+; the
       # +handler+ argument is the Sandbox's table, sharing the same
-      # allocator the guest→host return path (B-14) uses.
+      # allocator the guest→host return path uses.
       #
       # Layout: msgpack map with string keys +"entrypoint"+ (Symbol via
       # ext 0x00), +"args"+ (Array), +"kwargs"+ (Map with Symbol keys);
@@ -74,9 +71,9 @@ module Kobako
 
       private
 
-      # E-24: target must be a Symbol or String (TypeError, not
+      # The target must be a Symbol or String (TypeError, not
       # ArgumentError — the wrong-type case is a Host App programming
-      # error before the run reaches the guest). E-25: after +.to_s+
+      # error before the run reaches the guest). After +.to_s+
       # the value must match NAME_PATTERN (ArgumentError), rejecting
       # +::+-segmented names and any non-constant form.
       def normalize_entrypoint(target)
@@ -93,12 +90,12 @@ module Kobako
         target_str.to_sym
       end
 
-      # E-29: +args+ must not contain a +Kobako::Handle+. The Handle
+      # +args+ must not contain a +Kobako::Handle+. The Handle
       # allocator lives inside the Host Gem; legitimate paths surface
       # Handle objects only through raised error fields, so a Handle
       # reaching +args+ is a forged or smuggled token. Non-wire-
       # representable arguments that are not Handles are handled by
-      # auto-wrap inside +#encode+ (B-34) — the reject path is reserved
+      # auto-wrap inside +#encode+ — the reject path is reserved
       # for Handle objects specifically.
       def validate_args!(args)
         raise ArgumentError, "arguments must be an Array" unless args.is_a?(Array)
@@ -107,11 +104,10 @@ module Kobako
         args
       end
 
-      # E-30 covers the non-Symbol kwargs-key case; E-29 also rejects a
-      # +Kobako::Handle+ arriving as a kwargs value (same forged-token
-      # principle as the +args+ branch). Both checks live here so the
-      # Host App sees the host-side error message before any encode /
-      # decode boundary.
+      # Reject a non-Symbol kwargs key, and a +Kobako::Handle+ arriving
+      # as a kwargs value (same forged-token principle as the +args+
+      # branch). Both checks live here so the Host App sees the
+      # host-side error message before any encode / decode boundary.
       def validate_kwargs!(kwargs)
         raise ArgumentError, "keyword arguments must be a Hash" unless kwargs.is_a?(Hash)
 
@@ -125,11 +121,10 @@ module Kobako
         kwargs
       end
 
-      # Single source of truth for the E-29 reject message so the args
-      # and kwargs branches stay phrased identically. Message stays in
+      # Single source of truth for the forged-Handle reject message so the
+      # args and kwargs branches stay phrased identically. Message stays in
       # caller vocabulary: it names the affected slot and the reason
-      # without leaking SPEC anchor identifiers (B-xx / E-xx live in
-      # source comments, not user-visible errors) or self-referential
+      # without leaking internal SPEC identifiers or self-referential
       # architecture terms — the error is raised BY kobako, so saying
       # "allocated by the Host Gem" reads as third-person about self.
       def forged_handle_message(slot)

data/lib/kobako/transport/yielder.rb

@@ -8,29 +8,25 @@ module Kobako
   # owns the host-side object that materialises a guest-supplied block as
   # a Ruby callable the Service method can yield into.
   module Transport
-    # Host-side stand-in for a guest-supplied block (B-23).
+    # Host-side stand-in for a guest-supplied block.
     #
     # Each guest call that carries +block_given: true+ gets a Yielder
     # that the Dispatcher hands to the Service method as +&block+. The
     # Service method observes it as an ordinary Ruby Proc through
     # {#to_proc}; +yield val+ / +block.call(val)+ invokes {#yield}, which
     # serialises the positional args, re-enters the guest via the injected
-    # +yield_to_guest+ lambda
-    # ({docs/behavior.md B-24}[link:../../../docs/behavior.md]), and
-    # reifies the +YieldResponse+ into Ruby control flow:
+    # +yield_to_guest+ lambda, and reifies the +YieldResponse+ into Ruby
+    # control flow:
     #
     #   * +tag 0x01+ ok    — return the decoded value to +yield+'s caller
     #   * +tag 0x02+ break — +throw break_tag, value+ so the Dispatcher's
     #     +catch+ frame unwinds the Service method
-    #     ({docs/behavior.md B-25}[link:../../../docs/behavior.md])
     #   * +tag 0x04+ error — raise the +{class, message}+ payload at the
     #     Service's yield site
     #
     # The Dispatcher calls {#invalidate!} from its +ensure+ block once
     # dispatch completes; any later call to a stashed Yielder then raises
-    # +LocalJumpError+ — the observable shape of
-    # {docs/behavior.md E-23}[link:../../../docs/behavior.md] (escaped
-    # Yielder).
+    # +LocalJumpError+ — the observable shape of an escaped Yielder.
     class Yielder
       # +yield_to_guest+ is a +String → String+ callable (typically
       # +Runtime#yield_to_active_invocation+ bound through a lambda) that
@@ -38,8 +34,7 @@ module Kobako
       # throw tag the Dispatcher matches against to unwind the Service on
       # +tag 0x02+. +handler+ is the Sandbox's +Kobako::Catalog::Handles+,
       # used to restore a Capability Handle in the block's ok value back to
-      # its host object before it reaches the Service +yield+ site
-      # ({docs/behavior.md B-37}[link:../../../docs/behavior.md]).
+      # its host object before it reaches the Service +yield+ site.
       def initialize(yield_to_guest, break_tag, handler)
         @yield_to_guest = yield_to_guest
         @break_tag = break_tag
@@ -49,10 +44,10 @@ module Kobako
 
       # Re-enter the guest with +args+ and reify the YieldResponse into
       # Ruby control flow. Raises +LocalJumpError+ if called after
-      # {#invalidate!} (E-23). The ok value is consumed by the host Service
-      # method, so a Capability Handle in it is restored to its host object
-      # (B-37). The break value unwinds past the Service back to the guest
-      # Member call (B-25), so it passes through verbatim — a Handle stays a
+      # {#invalidate!}. The ok value is consumed by the host Service
+      # method, so a Capability Handle in it is restored to its host object.
+      # The break value unwinds past the Service back to the guest
+      # Member call, so it passes through verbatim — a Handle stays a
       # Handle and rides back on the same id rather than churning a new one.
       def yield(*args)
         raise LocalJumpError, "guest block invoked after host dispatch frame returned" unless @active
@@ -73,7 +68,7 @@ module Kobako
 
       # Mark this Yielder dead. Called by the Dispatcher's +ensure+ block
       # when the originating dispatch frame returns; any later {#yield}
-      # call then raises +LocalJumpError+ (E-23).
+      # call then raises +LocalJumpError+.
       def invalidate!
         @active = false
       end
@@ -81,8 +76,7 @@ module Kobako
       private
 
       # Restore any Capability Handle in a block's ok value to its host
-      # object via the injected +Catalog::Handles+
-      # ({docs/behavior.md B-37}[link:../../../docs/behavior.md]). Only the
+      # object via the injected +Catalog::Handles+. Only the
       # ok path calls this — host code consumes the ok value, whereas a
       # break value returns to the guest and stays a Handle. Walks nested
       # Array / Hash one level at a time; a plain value passes through

data/lib/kobako/transport.rb

@@ -13,9 +13,8 @@ module Kobako
   # Houses the envelope value objects (Request / Response / Run / Yield),
   # the guest→host +Dispatcher+, and the host→guest +Yielder+.
   # +Sandbox#initialize+ composes them onto the
-  # +Runtime+ as a dispatch +Proc+ + +yield_to_guest+ lambda pair
-  # ({docs/behavior.md B-12}[link:../../docs/behavior.md]). "RPC" was
-  # deliberately not chosen — it implies a cross-process boundary that
+  # +Runtime+ as a dispatch +Proc+ + +yield_to_guest+ lambda pair.
+  # "RPC" was deliberately not chosen — it implies a cross-process boundary that
   # kobako does not have, since host and guest share one OS thread and
   # one wasm linear memory. See
   # {SPEC.md Refinement → Internal Concepts}[link:../../SPEC.md].

data/lib/kobako/usage.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
 module Kobako
-  # Per-last-invocation resource accounting for a +Kobako::Sandbox+
-  # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Carries two
-  # readers populated by every +#eval+ / +#run+ invocation:
+  # Per-last-invocation resource accounting for a +Kobako::Sandbox+.
+  # Carries two readers populated by every +#eval+ / +#run+ invocation:
   #
   #   * +wall_time+ — the Float number of seconds the guest export call
   #     spent inside wasmtime during the most recent invocation. The
-  #     measurement bracket aligns with the +timeout+ deadline
-  #     ({docs/behavior.md B-01}[link:../../docs/behavior.md]); time spent
+  #     measurement bracket aligns with the +timeout+ deadline; time spent
   #     in host Service callbacks is included, but everything that runs
   #     after the guest export returns — the post-export
   #     +OUTCOME_BUFFER+ fetch and decode, plus stdout / stderr capture
@@ -16,11 +14,11 @@ module Kobako
   #   * +memory_peak+ — the Integer high-water mark, in bytes, of the
   #     per-invocation +memory.grow+ delta past the linear-memory size
   #     captured at invocation entry. Same baseline accounting as
-  #     +memory_limit+ ({docs/behavior.md E-20}[link:../../docs/behavior.md]):
-  #     the mruby image's initial allocation and any prior-invocation
-  #     watermark sit outside the measurement. On +MemoryLimitError+
-  #     +memory_peak+ never exceeds the configured cap because the
-  #     rejected +desired+ value is not promoted into the high-water.
+  #     +memory_limit+: the mruby image's initial allocation and any
+  #     prior-invocation watermark sit outside the measurement. On
+  #     +MemoryLimitError+ +memory_peak+ never exceeds the configured
+  #     cap because the rejected +desired+ value is not promoted into
+  #     the high-water.
   #
   # Both readers are populated on every outcome, including +TrapError+
   # branches, so the Host App can read +Sandbox#usage+ after rescuing a
@@ -31,9 +29,8 @@ module Kobako
   # Built on the +class X < Data.define(...)+ subclass form (the
   # Steep-friendly shape — see +lib/kobako/outcome/panic.rb+).
   class Usage < Data.define(:wall_time, :memory_peak)
-    # Pre-invocation sentinel ({docs/behavior.md B-35}[link:../../docs/behavior.md]).
-    # Reused by +Sandbox+ before any invocation has run so callers do not
-    # need to handle a +nil+ +#usage+.
+    # Pre-invocation sentinel. Reused by +Sandbox+ before any invocation
+    # has run so callers do not need to handle a +nil+ +#usage+.
     EMPTY = new(wall_time: 0.0, memory_peak: 0)
   end
 end

data/lib/kobako/version.rb

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

data/lib/kobako.rb

@@ -15,3 +15,4 @@ require_relative "kobako/catalog"
 require_relative "kobako/runtime"
 require_relative "kobako/snapshot"
 require_relative "kobako/sandbox"
+require_relative "kobako/pool"

data/release-please-config.json

@@ -73,13 +73,28 @@
           "path": "/wasm/kobako-regexp/README.md"
         }
       ]
+    },
+    "wasm/kobako-baker": {
+      "component": "kobako-baker",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/wasm/kobako-baker/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-baker')].version"
+        },
+        {
+          "type": "generic",
+          "path": "/wasm/kobako-baker/README.md"
+        }
+      ]
     }
   },
   "plugins": [
     {
       "type": "linked-versions",
       "groupName": "kobako guest crates",
-      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-regexp"]
+      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-regexp", "kobako-baker"]
     }
   ],
   "extra-files": [

data/sig/kobako/catalog/handles.rbs

@@ -1,8 +1,6 @@
 module Kobako
   module Catalog
     class Handles
-      UNWRAPPABLE_TYPES: Array[Module]
-
       def initialize: (?next_id: Integer) -> void
 
       def alloc: (untyped object) -> Kobako::Handle

data/sig/kobako/errors.rbs

@@ -52,4 +52,7 @@ module Kobako
 
   class BytecodeError < SandboxError
   end
+
+  class PoolTimeoutError < Error
+  end
 end

data/sig/kobako/namespace.rbs

@@ -8,6 +8,8 @@ module Kobako
 
     def bind: (Symbol | String member, untyped object) -> self
 
+    def seal!: () -> self
+
     def fetch: (Symbol | String member) -> untyped
 
     def to_preamble: () -> [String, Array[String]]

data/sig/kobako/pool.rbs

@@ -0,0 +1,44 @@
+module Kobako
+  class Pool
+    DEFAULT_CHECKOUT_TIMEOUT_SECONDS: Float
+
+    @slots: Integer
+    @checkout_timeout: Float?
+    @sandbox_options: Hash[Symbol, untyped]
+    @setup: ^(Kobako::Sandbox) -> void | nil
+    @idle: Array[Kobako::Sandbox]
+    @constructed: Integer
+    @mutex: Thread::Mutex
+    @slot_freed: Thread::ConditionVariable
+
+    def initialize: (
+      slots: Integer,
+      ?checkout_timeout: (Float | Integer)?,
+      **untyped sandbox_options
+    ) ?{ (Kobako::Sandbox) -> void } -> void
+
+    def with: [T] () { (Kobako::Sandbox) -> T } -> T
+
+    private
+
+    def checkout: () -> Kobako::Sandbox
+
+    def acquire: () -> Kobako::Sandbox
+
+    def claim_or_wait: (Float? deadline) -> [Symbol, Kobako::Sandbox?]
+
+    def await_slot!: (Float? deadline) -> void
+
+    def construct_slot: () -> Kobako::Sandbox
+
+    def checkin: (Kobako::Sandbox sandbox) -> void
+
+    def release_capacity!: () -> void
+
+    def monotonic_now: () -> Float
+
+    def validate_slots!: (untyped slots) -> void
+
+    def normalize_checkout_timeout: ((Float | Integer)? checkout_timeout) -> Float?
+  end
+end

data/sig/kobako/sandbox.rbs

@@ -38,12 +38,12 @@ module Kobako
 
     def eval: (String code) -> untyped
 
+    def reset_invocation_state!: () -> void
+
     private
 
     def install_dispatch_proc!: () -> void
 
-    def reset_invocation_state!: () -> void
-
     def begin_invocation!: () -> void
 
     def read_usage!: () -> void

data/sig/kobako/transport/dispatcher.rbs

@@ -22,6 +22,8 @@ module Kobako
 
       def self?.reject_meta_method!: (untyped target, Symbol name) -> void
 
+      def self?.reject_unexposed!: (untyped target, Symbol name) -> void
+
       def self?.resolve_arg: (untyped value, Kobako::Catalog::Handles handler) -> untyped
 
       def self?.resolve_target: (String | Kobako::Handle target, Kobako::Catalog::Namespaces namespaces, Kobako::Catalog::Handles handler) -> untyped

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.11.0
 platform: aarch64-linux
 authors:
 - Aotokitsuruya
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-06-11 00:00:00.000000000 Z
+date: 2026-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: msgpack
@@ -59,6 +59,7 @@ files:
 - lib/kobako/namespace.rb
 - lib/kobako/outcome.rb
 - lib/kobako/outcome/panic.rb
+- lib/kobako/pool.rb
 - lib/kobako/runtime.rb
 - lib/kobako/sandbox.rb
 - lib/kobako/sandbox_options.rb
@@ -96,6 +97,7 @@ files:
 - sig/kobako/namespace.rbs
 - sig/kobako/outcome.rbs
 - sig/kobako/outcome/panic.rbs
+- sig/kobako/pool.rbs
 - sig/kobako/runtime.rbs
 - sig/kobako/sandbox.rbs
 - sig/kobako/sandbox_options.rbs