kobako 0.18.0 → 0.20.0

data/lib/kobako/extension.rb

@@ -27,17 +27,31 @@ module Kobako
     # 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).
+    # idiom routes to) with the source of the bound object, declared by
+    # explicit keyword:
     #
-    # 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)
+    #   * +object:+ — a static object, fixed for the Sandbox's life.
+    #   * +provider:+ — a no-argument callable invoked once per invocation to
+    #     yield that invocation's object, so a fresh object backs the path
+    #     every invocation. A provider that raises propagates its exception to
+    #     the invocation caller and leaves the guest unrun; the next
+    #     invocation resolves it afresh.
+    #   * neither — a fillable, defaulting to +Kobako::Unresolved+ until the
+    #     host supplies the invocation's object.
+    #
+    # The kind is chosen by keyword, never inferred from whether the value is
+    # callable, so a static object that is itself callable is expressed
+    # directly with +object:+. Giving both +object:+ and +provider:+ raises
+    # +ArgumentError+.
+    class Backend < Data.define(:path, :object, :provider)
+      def initialize(path:, object: nil, provider: nil)
+        if !object.nil? && !provider.nil?
+          raise ArgumentError,
+                "Extension::Backend accepts object: or provider:, not both"
+        end
+
+        super
+      end
     end
 
     # +backend+ and +depends_on+ default to absent so the common

data/lib/kobako/pool.rb

@@ -47,7 +47,7 @@ module Kobako
     # discarded and its slot refills by a fresh construction on next
     # demand.
     def with
-      sandbox = checkout
+      sandbox = acquire
       begin
         yield sandbox
       rescue TrapError
@@ -61,12 +61,6 @@ module Kobako
 
     private
 
-    # Acquire a Sandbox and hand it over in pre-invocation state — empty
-    # output buffers and truncation predicates false.
-    def checkout
-      acquire.tap(&:reset_invocation_state!)
-    end
-
     # The idle-first claim loop: an idle Sandbox wins, unclaimed
     # capacity constructs, and a full pool waits for a checkin.
     def acquire

data/lib/kobako/sandbox.rb

@@ -2,37 +2,33 @@
 
 require "forwardable"
 
-require_relative "capture"
-require_relative "codec"
 require_relative "errors"
-require_relative "outcome"
+require_relative "unresolved"
 require_relative "sandbox_options"
-require_relative "usage"
 require_relative "transport"
 require_relative "catalog"
+require_relative "context"
 
 module Kobako
   # Kobako::Sandbox — the user-facing entry point for executing guest mruby
   # scripts inside a wasmtime-hosted Wasm module.
   #
-  # The Sandbox owns the +Kobako::Runtime+, the per-Sandbox
-  # +Kobako::Catalog::Handles+, the per-instance
-  # +Kobako::Catalog::Services+ (which receives the +Catalog::Handles+ by
-  # injection so guest→host dispatch and host→guest auto-wrap share one
-  # allocator), and the dispatch +Proc+ / +yield_to_guest+ lambda installed
-  # on the Runtime via +Runtime#on_dispatch=+. The underlying wasmtime Engine
-  # and compiled Module are cached at process scope by the native ext and
-  # never surface to Ruby — constructing many Sandboxes amortises both costs
+  # The Sandbox owns the reusable configuration — the +Kobako::Runtime+ and
+  # the +Kobako::Catalog::Services+ / +Catalog::Snippets+ / +Catalog::Extensions+
+  # registries. Each +#eval+ / +#run+ seals that config on the first call and
+  # drives one guest invocation through a fresh +Kobako::Context+ — its own
+  # Handle table, dispatch +Proc+, captures, and usage — so the reusable
+  # Sandbox holds no per-invocation state. The underlying wasmtime Engine and
+  # compiled Module are cached at process scope by the native ext and never
+  # surface to Ruby — constructing many Sandboxes amortises both costs
   # automatically.
   #
-  # Output capture policy: the
-  # per-channel cap (+stdout_limit+ / +stderr_limit+) is enforced inside the
-  # WASI pipe — the host buffer stops growing at the cap, subsequent guest
-  # writes on that channel fail or are dropped, and +#run+ still returns
-  # normally. +#stdout+ / +#stderr+ return the captured prefix as a UTF-8
-  # String; the byte content never carries a truncation sentinel.
-  # +#stdout_truncated?+ / +#stderr_truncated?+ are the only way to observe
-  # that the cap was hit.
+  # A run's observables — the captured +#stdout+ / +#stderr+ (bounded by
+  # +stdout_limit+ / +stderr_limit+, enforced inside the WASI pipe) with their
+  # +#stdout_truncated?+ / +#stderr_truncated?+ predicates, and +#usage+ — live
+  # on the +Kobako::Execution+ each +#eval+ / +#run+ returns, or on the one its
+  # raised error carries. The Sandbox itself keeps none of them, so nothing a
+  # run observes carries into the next one.
   class Sandbox
     extend Forwardable
 
@@ -40,39 +36,7 @@ module Kobako
 
     # Per-option accessors forward to the immutable +SandboxOptions+ Value
     # Object so the Host App still reads them off Sandbox directly.
-    def_delegators :@options, :timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile
-
-    # Returns the bytes the guest wrote to stdout during the most recent
-    # invocation as a UTF-8 String, clipped at +stdout_limit+. Empty before
-    # any invocation; the byte content never contains a truncation sentinel,
-    # 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
-
-    # 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
-
-    # 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?
-
-    # Returns +true+ iff stderr capture during the most recent invocation
-    # exceeded +stderr_limit+. Mirror of +#stdout_truncated?+.
-    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
-    # inside wasmtime) and +memory_peak+ (Integer bytes, high-water of
-    # the per-invocation +memory.grow+ delta past the entry-time
-    # baseline). Returns +Kobako::Usage::EMPTY+ before any invocation;
-    # populated on every outcome — including +TrapError+ — so the Host
-    # App can read it after rescuing a trap to diagnose budget
-    # consumption.
-    attr_reader :usage
+    def_delegators :@options, :timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile, :gvl
 
     # Build a fresh Sandbox.
     #
@@ -91,13 +55,10 @@ module Kobako
     def initialize(wasm_path: nil, **)
       @wasm_path = wasm_path || Kobako::Runtime.default_path
       @options = SandboxOptions.new(**)
-      @handler = Catalog::Handles.new
-      @services = Kobako::Catalog::Services.new(handler: @handler)
+      @services = Kobako::Catalog::Services.new
       @snippets = Catalog::Snippets.new
       @extensions = Catalog::Extensions.new
       @runtime = build_runtime!
-      install_dispatch_proc!
-      reset_invocation_state!
     end
 
     # Bind +object+ as the Service reachable at +path+ — a Symbol or
@@ -105,11 +66,17 @@ module Kobako
     # (+"MyService::KV"+ or a top-level +"File"+). Returns +self+ for
     # chaining.
     #
+    # Called with only a +path+, it declares a fillable Service:
+    # +bind(path)+ reserves the path for +Kobako::Unresolved+, so the guest
+    # sees the constant while the host defers the object it stands for. A
+    # guest dispatch to an unfilled fillable surfaces as
+    # +Kobako::ServiceError+ when left unrescued.
+    #
     # Raises +ArgumentError+ when a segment is malformed, when +path+
     # collides with an existing binding (a name is a bound Service or a
     # grouping prefix, never both), or when called after the first
     # invocation has sealed Service registration.
-    def bind(path, object)
+    def bind(path, object = Unresolved)
       @services.bind(path, object)
       self
     end
@@ -175,11 +142,9 @@ module Kobako
     # deserialized result. The first invocation seals the Service registry
     # and snippet table. Runtime errors follow the same three-class
     # taxonomy as +#eval+.
-    def run(target, *args, **kwargs)
+    def run(target, *args, **kwargs, &block)
       run_envelope = Transport::Run.new(entrypoint: target, args: args, kwargs: kwargs)
-      invoke!(:run) do
-        @runtime.run(@services.encode, @snippets.encode, run_envelope.encode(@handler))
-      end
+      new_invocation.run(run_envelope, &block)
     end
 
     # Execute a guest mruby source string in a fresh +mrb_state+. +code+ is
@@ -203,24 +168,10 @@ module Kobako
     # (including when +code+ is +nil+ or not a String, or when a preloaded
     # snippet's replay raises); +Kobako::ServiceError+ on an unrescued
     # Service capability failure.
-    def eval(code)
+    def eval(code, &block)
       raise SandboxError, "code must be a String, got #{code.class}" unless code.is_a?(String)
 
-      invoke!(:eval) do
-        @runtime.eval(@services.encode, code.b, @snippets.encode)
-      end
-    end
-
-    # Reset all per-invocation observable state to its pre-invocation
-    # sentinels — both per-channel captures and the per-last-invocation
-    # usage record. Shared by +#initialize+ (first-time setup) and
-    # +#begin_invocation!+ (between-invocation reset) so both paths agree on
-    # what "pre-invocation state" means; +Kobako::Pool+ calls it at checkout
-    # so a pooled Sandbox hands over empty output buffers.
-    def reset_invocation_state!
-      @stdout_capture = Capture::EMPTY
-      @stderr_capture = Capture::EMPTY
-      @usage = Usage::EMPTY
+      new_invocation.eval(code, &block)
     end
 
     private
@@ -231,119 +182,29 @@ module Kobako
     # runtime that cannot honor the request never runs guest code.
     def build_runtime!
       runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
-                                          @options.stdout_limit, @options.stderr_limit, @options.profile)
+                                          @options.stdout_limit, @options.stderr_limit, @options.profile,
+                                          @options.gvl)
       @options.enforce_floor!(runtime.profile)
       runtime
     end
 
-    # Configure the +Runtime+'s host↔guest dispatch wiring. Registers a
-    # dispatch +Proc+ that routes guest→host calls through the stateless
-    # +Transport::Dispatcher+, capturing +@services+ / +@handler+ in the
-    # closure. The ext hands the +Proc+ a per-dispatch +guest_yielder+ — a
-    # +String → String+ callable that re-enters the in-flight guest to run a
-    # yielded block — which the +Dispatcher+ forwards to the +Transport::Yielder+
-    # it builds for the call. Registered once at construction time so the
-    # wasm ext callback can fire without further setup.
-    def install_dispatch_proc!
-      @runtime.on_dispatch = lambda do |request_bytes, guest_yielder|
-        Transport::Dispatcher.dispatch(request_bytes, @services, @handler, guest_yielder)
-      end
+    # Seal the config on the first invocation and return a fresh
+    # per-invocation +Context+ for the verb to drive. The Context owns this
+    # run's Handle table, resolved Extension backends, captures, and usage, so
+    # no per-invocation state is written back onto the shared config.
+    def new_invocation
+      begin_invocation!
+      Context.new(runtime: @runtime, services: @services, snippets: @snippets, extensions: @extensions)
     end
 
-    # 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.
+    # Per-invocation prologue on the config tier: seals the Service / snippet /
+    # Extension registries on the first call (idempotent — asserting Extension
+    # dependencies then). Per-invocation provider resolution and observable
+    # state live on the +Context+, not here.
     def begin_invocation!
       @services.seal!
+      @snippets.seal!
       @extensions.seal!
-      @extensions.refresh_backends!(@services)
-      @handler.reset!
-      reset_invocation_state!
-    end
-
-    # Read the per-last-invocation +wall_time+ and +memory_peak+ from
-    # the ext and wrap them as a +Kobako::Usage+ value object. Runs in
-    # the +invoke!+ +ensure+ block so the usage record is populated on
-    # every outcome — value return, +Kobako::TrapError+ (including
-    # +TimeoutError+ / +MemoryLimitError+), +Kobako::SandboxError+,
-    # and +Kobako::ServiceError+. +Runtime#usage+ is the single source for
-    # both paths: the figures are stashed in the ext on every outcome, so
-    # the readout here also covers the trap path, where +Runtime#eval+ /
-    # +#run+ raise instead of returning outcome bytes.
-    #
-    # The ext-side contract is positional: +Runtime#usage+ yields
-    # +[wall_time, memory_peak]+ in +Kobako::Usage+ field order.
-    def read_usage!
-      wall_time, memory_peak = @runtime.usage
-      @usage = Usage.new(wall_time: wall_time, memory_peak: memory_peak)
-    end
-
-    # Pick the +TrapError+ subclass to re-raise based on +err+'s actual
-    # class. Cap-trap subclasses (+TimeoutError+ / +MemoryLimitError+)
-    # preserve their named identity; everything else collapses to the
-    # base +Kobako::TrapError+. The ext already raises the right subclass
-    # directly, so this is a pure re-attribution that lets +#invoke!+
-    # add the verb prefix without erasing +TimeoutError+ /
-    # +MemoryLimitError+.
-    def trap_class_for(err)
-      case err
-      when TimeoutError     then TimeoutError
-      when MemoryLimitError then MemoryLimitError
-      else TrapError
-      end
-    end
-
-    # Read the per-last-invocation output captures from the ext and wrap
-    # them as +Kobako::Capture+ value objects. Runs in the +invoke!+
-    # +ensure+ block next to #read_usage! for the same reason: the ext
-    # stashes the captures on every outcome, so the readout also covers
-    # the trap path, where +Runtime#eval+ / +#run+ raise instead of
-    # returning outcome bytes — +#stdout+ / +#stderr+ keep the guest's
-    # partial output readable after a rescue.
-    #
-    # The ext-side contract is positional: +Runtime#captures+ yields
-    # +[stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated]+.
-    def read_captures!
-      stdout_bytes, stdout_truncated, stderr_bytes, stderr_truncated = @runtime.captures
-      @stdout_capture = Capture.new(bytes: stdout_bytes, truncated: stdout_truncated)
-      @stderr_capture = Capture.new(bytes: stderr_bytes, truncated: stderr_truncated)
-    end
-
-    # Shared prologue / epilogue + trap-class translator for both
-    # invocation verbs. +verb+ is +:eval+ or +:run+; it tags the
-    # TrapError message so the failing export is identifiable.
-    #
-    # The yielded block must return the invocation's raw outcome bytes —
-    # i.e. the value of +Runtime#eval+ / +#run+ — which the success path
-    # feeds to +Outcome.decode+. Captures and usage are populated by the
-    # +ensure+ readouts (#read_usage! / #read_captures!) on every
-    # outcome, so +#stdout+ / +#stderr+ / +#usage+ stay readable after a
-    # rescued trap.
-    # The rescue chain is the single trap-translation boundary —
-    # configured-cap paths surface as named TrapError subclasses
-    # (+TimeoutError+ / +MemoryLimitError+); everything else surfaces as
-    # the base +TrapError+.
-    def invoke!(verb)
-      begin_invocation!
-      return_bytes = yield
-      # A Capability Handle in the result is decoded as a Kobako::Handle
-      # token; restore it to the host object the guest referenced before
-      # handing the value to the Host App. @handler still holds this
-      # invocation's table — reset only happens at the next #begin_invocation!.
-      # A Handle-free result resolves to itself, so the restoration walk is
-      # skipped when the decode carried none.
-      value, carried_handle = Codec.track_handles { Outcome.decode(return_bytes) }
-      carried_handle ? Codec::HandleWalk.deep_restore(value, @handler) : value
-    rescue Kobako::TrapError => e
-      raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
-    ensure
-      read_usage!
-      read_captures!
     end
   end
 end

data/lib/kobako/sandbox_options.rb

@@ -21,7 +21,7 @@ module Kobako
   # as-is. The options also own the ladder comparison
   # (+#enforce_floor!+) that +Kobako::Sandbox+ delegates its
   # construction floor check to.
-  class SandboxOptions < Data.define(:timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile)
+  class SandboxOptions < Data.define(:timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile, :gvl)
     # Default wall-clock timeout for a single invocation: 60 seconds.
     DEFAULT_TIMEOUT_SECONDS = 60.0
 
@@ -41,16 +41,28 @@ module Kobako
     # +:permissive+ is the Host App's explicit trade.
     DEFAULT_PROFILE = :hermetic
 
+    # The GVL scheduling modes: +:hold+ keeps Ruby's GVL for the whole
+    # invocation, +:release+ drops it for the guest span so distinct
+    # Sandboxes on distinct Threads run their guest code in parallel.
+    GVL_MODES = %i[hold release].freeze
+
+    # Default GVL mode: +:hold+ — holding the GVL matches single-threaded
+    # execution, so +:release+ is the Host App's explicit opt-in for
+    # host-parallel guest execution.
+    DEFAULT_GVL = :hold
+
     def initialize(timeout: DEFAULT_TIMEOUT_SECONDS,
                    memory_limit: DEFAULT_MEMORY_LIMIT,
                    stdout_limit: DEFAULT_OUTPUT_LIMIT,
                    stderr_limit: DEFAULT_OUTPUT_LIMIT,
-                   profile: DEFAULT_PROFILE)
+                   profile: DEFAULT_PROFILE,
+                   gvl: DEFAULT_GVL)
       timeout = normalize_timeout(timeout)
       memory_limit = normalize_memory_limit(memory_limit)
       stdout_limit = normalize_output_limit(stdout_limit, "stdout_limit")
       stderr_limit = normalize_output_limit(stderr_limit, "stderr_limit")
       profile = normalize_profile(profile)
+      gvl = normalize_gvl(gvl)
       super
     end
 
@@ -120,5 +132,14 @@ module Kobako
 
       raise ArgumentError, "profile must be one of #{PROFILES.map(&:inspect).join(", ")}, got #{profile.inspect}"
     end
+
+    # Validate +gvl+ against GVL_MODES. Like +profile+ it has no +nil+
+    # form: the scheduling mode is requested as an explicit Symbol, so
+    # anything off the set — +nil+ included — is rejected.
+    def normalize_gvl(gvl)
+      return gvl if GVL_MODES.include?(gvl)
+
+      raise ArgumentError, "gvl must be one of #{GVL_MODES.map(&:inspect).join(", ")}, got #{gvl.inspect}"
+    end
   end
 end

data/lib/kobako/transport/dispatcher.rb

@@ -13,7 +13,8 @@ module Kobako
   module Transport
     # Pure-function dispatcher for guest-initiated transport calls.
     # Decodes a msgpack-encoded Request envelope, resolves the target
-    # object through the Catalog::Services (path lookup) or
+    # object through the per-invocation path +resolver+ (the +Context+, whose
+    # +#lookup+ layers per-invocation providers over the static bindings) or
     # Catalog::Handles (Handle lookup), invokes the method, and returns
     # a msgpack-encoded Response envelope.
     #
@@ -24,7 +25,7 @@ module Kobako
     #
     # Entry point:
     #
-    #   Kobako::Transport::Dispatcher.dispatch(request_bytes, services, handler, yield_to_guest)
+    #   Kobako::Transport::Dispatcher.dispatch(request_bytes, resolver, handler, yield_to_guest)
     #   # => msgpack-encoded Response bytes (never raises)
     module Dispatcher
       # Throw tag for the Yielder's break unwind back to the
@@ -66,12 +67,12 @@ module Kobako
       private_constant :CALLABLE_ALLOW
 
       # Dispatch a single transport request and return the encoded
-      # Response bytes. Invoked from the +Runtime#on_dispatch+ Proc that
-      # +Kobako::Sandbox#initialize+ installs on the ext side; +services+,
+      # Response bytes. Invoked from the per-invocation dispatch Proc that
+      # +Kobako::Context+ hands to +Runtime#eval+ / +#run+; +resolver+,
       # +handler+, and +yield_to_guest+ are captured in that Proc's
-      # closure so the Dispatcher stays stateless and the registry doesn't
-      # need to publish accessors for the Sandbox-owned +Catalog::Handles+
-      # or +Runtime+. +yield_to_guest+ is a +String → String+ callable
+      # closure so the Dispatcher stays stateless and neither the resolver
+      # nor the Context needs to publish accessors for the per-invocation
+      # +Catalog::Handles+ or +Runtime+. +yield_to_guest+ is a +String → String+ callable
       # (the ext's per-dispatch +Kobako::Runtime::GuestYielder+) used only
       # when the Request carries +block_given: true+. Always
       # returns a binary String — every failure path is reified as a
@@ -81,9 +82,9 @@ module Kobako
       # The decode runs inside +Codec.track_handles+ so #resolve_call_args
       # can skip the argument walk when no Capability Handle crossed the
       # wire.
-      def dispatch(request_bytes, services, handler, yield_to_guest)
+      def dispatch(request_bytes, resolver, handler, yield_to_guest)
         request, carried_handle = Kobako::Codec.track_handles { Kobako::Transport::Request.decode(request_bytes) }
-        target = resolve_target(request.target, services, handler)
+        target = resolve_target(request.target, resolver, handler)
         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)
@@ -192,24 +193,24 @@ module Kobako
         raise UndefinedTargetError, e.message
       end
 
-      # Resolve a Request target to the Ruby object the registry (or
-      # Catalog::Handles) holds. String targets go through the registry;
+      # Resolve a Request target to the Ruby object the path +resolver+ (or
+      # Catalog::Handles) holds. String targets go through the resolver;
       # Handle targets (ext 0x01) go through the Catalog::Handles.
       #
       # Target type is already validated by +Transport::Request.decode+
       # before this method is reached, so no else-branch is needed here —
       # the wire layer is the system boundary that enforces the invariant.
-      def resolve_target(target, services, handler)
+      def resolve_target(target, resolver, handler)
         case target
         when String
-          resolve_path(target, services)
+          resolve_path(target, resolver)
         when Kobako::Handle
           require_live_object!(target.id, handler)
         end
       end
 
-      def resolve_path(path, services)
-        services.lookup(path)
+      def resolve_path(path, resolver)
+        resolver.lookup(path)
       rescue KeyError => e
         raise UndefinedTargetError, e.message
       end

data/lib/kobako/transport/yielder.rb

@@ -47,7 +47,7 @@ module Kobako
       # #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
+      # bound-constant 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

data/lib/kobako/unresolved.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Kobako::Unresolved — the sentinel backing a fillable Service path: one
+  # declared with +Sandbox#bind(path)+ carrying no object. It reserves the
+  # path's Frame 1 slot so the guest sees the bound constant while the host
+  # defers the object it stands for. A guest dispatch to an unfilled fillable
+  # is refused as an unresolved target and surfaces as +Kobako::ServiceError+
+  # when the guest leaves it unrescued — the same capability-failure channel
+  # as an idiom with no backend bound.
+  #
+  # A single shared value; only its identity distinguishes it, so the dispatch
+  # layer recognises it with +equal?+. A Host App may name it at a +bind+ site
+  # to declare a fillable explicitly.
+  module Unresolved
+  end
+end

data/lib/kobako/usage.rb

@@ -21,16 +21,16 @@ module Kobako
   #     the high-water.
   #
   # Both readers are populated on every outcome, including +TrapError+
-  # branches, so the Host App can read +Sandbox#usage+ after rescuing a
-  # trap to diagnose how much of the budget the failing invocation
-  # consumed. Before the first invocation +Sandbox#usage+ returns the
-  # pre-invocation sentinel +Kobako::Usage::EMPTY+.
+  # branches, so the Host App can read +#usage+ off the run's
+  # +Kobako::Execution+ — the one a raised error carries on +#execution+ —
+  # after rescuing a trap to diagnose how much of the budget the failing
+  # invocation consumed.
   #
   # 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. Reused by +Sandbox+ before any invocation
-    # has run so callers do not need to handle a +nil+ +#usage+.
+    # Pre-run sentinel. A fresh +Kobako::Context+ holds it until its guest
+    # runs, so an Execution's +#usage+ is never +nil+.
     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.18.0"
+  VERSION = "0.20.0"
 end

data/lib/kobako.rb

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

data/release-please-config.json

@@ -1,13 +1,14 @@
 {
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
   "release-type": "ruby",
+  "bump-minor-pre-major": true,
   "last-release-sha": "98509af508988f708bf0d7a76a718bb0428a177e",
   "packages": {
     ".": {
       "component": "kobako",
       "include-component-in-tag": false,
       "release-type": "ruby",
-      "exclude-paths": ["wasm"]
+      "exclude-paths": ["wasm", "crates"]
     },
     "wasm/kobako-core": {
       "component": "kobako-core",

data/sig/kobako/catalog/extensions.rbs

@@ -7,21 +7,19 @@ module Kobako
 
       def seal!: () -> self
 
-      def refresh_backends!: (Kobako::Catalog::Services services) -> self
+      def resolve: () -> Hash[String, untyped]
 
       private
 
-      def refresh_backend: (untyped extension, Kobako::Catalog::Services services, Hash[untyped, untyped] resolved) -> void
+      def install_object: (untyped backend) -> untyped
+
+      def resolve_backend: (untyped extension, Hash[String, untyped] resolved, Hash[untyped, untyped] by_provider) -> 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/handles.rbs

@@ -7,8 +7,6 @@ module Kobako
 
       def fetch: (Integer id) -> untyped
 
-      def reset!: () -> self
-
       def size: () -> Integer
 
       private

data/sig/kobako/catalog/services.rbs

@@ -3,13 +3,13 @@ module Kobako
     class Services
       NAME_PATTERN: Regexp
 
-      def initialize: (?handler: Kobako::Catalog::Handles) -> void
+      def initialize: () -> void
 
       def bind: (Symbol | String path, untyped object) -> self
 
-      def lookup: (Symbol | String target) -> untyped
+      def bound?: (Symbol | String path) -> bool
 
-      def refresh: (Symbol | String path, untyped object) -> self
+      def lookup: (Symbol | String target) -> untyped
 
       def encode: () -> String
 

data/sig/kobako/catalog/snippets.rbs

@@ -11,6 +11,8 @@ module Kobako
 
       def encode: () -> String
 
+      def seal!: () -> self
+
       private
 
       def register_source!: (String? code, (Symbol | String)? name) -> Symbol