kobako 0.19.0-aarch64-linux → 0.20.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c5d8b9dc269e7579dbcfc7718f24dc7e9d715504e249d55ed82b6e1f8116c5c
-  data.tar.gz: 9c2027efa1ba39ab0f00efa45efe7b78b2f41f88fc13a40d1ddbffa3669c251d
+  metadata.gz: b09a439fa6c5bfc4598a565bc0ec6cfd026c65c48a39e9c9c0ae73c53ffb00d9
+  data.tar.gz: 0b1a09a6af7b5eabf918667c9efcc434952d693322fda2f71cf0195df174d21a
 SHA512:
-  metadata.gz: 6d46f6cd644c63213ee5f706753e5ed1cc4d2f535bd595b8047b6206a6a16d1a13f8c44fd34f8ad1dbf99a32678a69d5bb68de644917f4092320028753c35b6d
-  data.tar.gz: f845f7ce1364282a5be2cdf430a4d2c1a77e1181b54a3d5aa4b83a0765733d88920ef018316d5b761dcafebbddf647ac7c814ac0ff21399afa42f5a560646b91
+  metadata.gz: b5475e836c30518290c9b94eab8c0fe92c222efea64c93d909a099d50612e674a75733777fd3c37e884b7564dbc40fa46a3f90a04a26c9be40aa5d54dc548f1f
+  data.tar.gz: d76951bea7e5eae63d2c79052dcd3d2e03204afa738020f958139a7b293ae55624d94b8e11a6aa1a124f5b9094b281852e4fca6042c6dbf5d797e29dac874fc5

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.19.0","wasm/kobako-core":"0.11.0","wasm/kobako-mruby":"0.11.0","wasm/kobako-io":"0.11.0","wasm/kobako-json":"0.11.0","wasm/kobako-regexp":"0.11.0","wasm/kobako-baker":"0.11.0","crates/kobako-codec":"0.11.0","crates/kobako-runtime":"0.11.0","crates/kobako-wasmtime":"0.11.0","crates/kobako":"0.11.0"}
+{".":"0.20.0","wasm/kobako-core":"0.12.0","wasm/kobako-mruby":"0.12.0","wasm/kobako-io":"0.12.0","wasm/kobako-json":"0.12.0","wasm/kobako-regexp":"0.12.0","wasm/kobako-baker":"0.12.0","crates/kobako-codec":"0.12.0","crates/kobako-runtime":"0.12.0","crates/kobako-wasmtime":"0.12.0","crates/kobako":"0.12.0"}

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.20.0](https://github.com/elct9620/kobako/compare/v0.19.0...v0.20.0) (2026-07-24)
+
+
+### Features
+
+* **bench:** mark a run in progress with a pid lock file ([3ca85fb](https://github.com/elct9620/kobako/commit/3ca85fbe9860ce32d58c1a5bf4ff85cbdc210780))
+* **execution:** tell a nil-value success from a failure with #failed? ([2f3d382](https://github.com/elct9620/kobako/commit/2f3d382b24d65fabda7771429cd3adfc90a8c7e8))
+* **extension:** declare a backend's kind by explicit keyword ([3f6c628](https://github.com/elct9620/kobako/commit/3f6c6283080ba4346ac8ef878e469dab8039e650))
+* **sandbox:** add the gvl: hold/release scheduling option ([ca2a884](https://github.com/elct9620/kobako/commit/ca2a884415b3271c44b20d131536b3fe7c5a3077))
+* **sandbox:** declare fillable Service paths defaulting to Kobako::Unresolved ([1d60f76](https://github.com/elct9620/kobako/commit/1d60f764ddff3b5b10206993e2b281c838ec0022))
+* **sandbox:** fill and override declared paths per invocation with ctx.bind ([629ef7d](https://github.com/elct9620/kobako/commit/629ef7dfa35273c952685fefb4c5793b11886aee))
+* **sandbox:** return a frozen Kobako::Invocation from #eval and #run ([e9f4634](https://github.com/elct9620/kobako/commit/e9f463403bea26fad32e52d560b979684f555ed1))
+* **tasks:** gate the wasmtime driver against a magnus dependency ([268c3f6](https://github.com/elct9620/kobako/commit/268c3f65f53d64b465458bca5c0c9b0d0467df44))
+
+
+### Bug Fixes
+
+* **context:** raise ArgumentError for a spent ctx.bind ([2783bba](https://github.com/elct9620/kobako/commit/2783bba20f139554178389d4c860e0c280cab550))
+* **extension:** re-assert dependencies after a failed seal ([72839ba](https://github.com/elct9620/kobako/commit/72839bac6186e81a1d4323bd3f1eb4f10abf3d64))
+
 ## [0.19.0](https://github.com/elct9620/kobako/compare/v0.18.0...v0.19.0) (2026-07-19)
 
 

data/crates/kobako-runtime/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.12.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.11.0...kobako-runtime-v0.12.0) (2026-07-24)
+
+
+### Miscellaneous Chores
+
+* **kobako-runtime:** Synchronize kobako crates versions
+
 ## [0.11.0](https://github.com/elct9620/kobako/compare/kobako-runtime-v0.10.2...kobako-runtime-v0.11.0) (2026-07-19)
 
 

data/crates/kobako-runtime/README.md

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

data/crates/kobako-wasmtime/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.12.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.11.0...kobako-wasmtime-v0.12.0) (2026-07-24)
+
+
+### Miscellaneous Chores
+
+* **kobako-wasmtime:** Synchronize kobako crates versions
+
 ## [0.11.0](https://github.com/elct9620/kobako/compare/kobako-wasmtime-v0.10.2...kobako-wasmtime-v0.11.0) (2026-07-19)
 
 

data/crates/kobako-wasmtime/README.md

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

data/lib/kobako/catalog/extensions.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../unresolved"
+
 module Kobako
   module Catalog
     # Kobako::Catalog::Extensions — per-Sandbox registry of installed
@@ -7,7 +9,9 @@ module Kobako
     # 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.
+    # path to a fresh object for every invocation — returning that map to the
+    # driving +Context+ rather than mutating the shared registry, so
+    # concurrent invocations stay shared-nothing.
     #
     # Sealing and the reject-after-install guard are governed by the owning
     # Sandbox through +Catalog::Services#sealed?+, the shared seal signal;
@@ -21,77 +25,87 @@ module Kobako
 
       # 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.
+      # backend path in +services+. A static +object:+ binds directly; a
+      # per-invocation +provider:+ or a fillable backend reserves the path with
+      # +Kobako::Unresolved+ (the per-invocation result is layered onto the
+      # Context, a fillable stays Unresolved until filled). Raises
+      # +ArgumentError+ for the two shapes +#validate!+ owns — +source+ not a
+      # String, or a present +backend+ that omits +path+ / +object+ /
+      # +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
+        services.bind(backend.path, install_object(backend)) 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.
+      # installed Extension. Runs once, when the Sandbox first seals
+      # successfully; an unmet dependency raises +ArgumentError+ naming the
+      # gap, before the guest runs. The asserted flag flips only on success,
+      # so a seal that failed re-checks on the next attempt rather than
+      # silently passing a broken Sandbox. Idempotent across later invocations.
       def seal!
         return self if @asserted
 
-        @asserted = true
         assert_dependencies!
+        @asserted = true
         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
+      # Resolve each +provider:+-backed path to this invocation's object and
+      # return the +path => object+ map the driving +Context+ layers over the
+      # static base bindings. Distinct providers yield distinct objects; one
+      # provider shared by several Extensions is invoked once and its result
+      # shared, so provider identity is resource identity. Static and fillable
+      # backends are omitted — they stay the object bound at install in the
+      # base registry (+Kobako::Unresolved+ for a fillable).
+      def resolve
+        resolved = {} # : Hash[String, untyped]
+        by_provider = {} # : Hash[untyped, untyped]
+        by_provider.compare_by_identity
+        @entries.each { |extension| resolve_backend(extension, resolved, by_provider) }
+        resolved
       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)
+      # The object a backend binds at install: a static +object:+ directly, or
+      # +Kobako::Unresolved+ as the placeholder for a per-invocation +provider:+
+      # (layered onto the Context) or a fillable (neither keyword).
+      def install_object(backend) = backend.object.nil? ? Kobako::Unresolved : backend.object
+
+      # Resolve one Extension's +provider:+-backed path against the shared
+      # per-invocation identity cache (keyed by provider identity) and record
+      # it in +resolved+. A static or fillable backend is skipped — its object
+      # stays as bound at install in the base registry.
+      def resolve_backend(extension, resolved, by_provider)
         backend = extension.backend
         return unless backend
 
         provider = backend.provider
-        return unless callable?(provider)
+        return if provider.nil?
 
-        object = resolved.fetch(provider) { resolved[provider] = provider.call }
-        services.refresh(backend.path, object)
+        resolved[backend.path.to_s] = by_provider.fetch(provider) { by_provider[provider] = provider.call }
       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+.
+      # +backend+ that, when present, exposes +path+ / +object+ / +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)
+        return if backend.respond_to?(:path) && backend.respond_to?(:object) && backend.respond_to?(:provider)
 
-        raise ArgumentError, "Extension #backend must expose #path and #provider"
+        raise ArgumentError, "Extension #backend must expose #path, #object, and #provider"
       end
 
       def assert_dependencies!
@@ -110,13 +124,6 @@ module Kobako
       # 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/handles.rb

@@ -5,10 +5,10 @@ require_relative "../handle"
 module Kobako
   module Catalog
     # Host-side mapping from opaque integer Handle IDs to Ruby objects.
-    # The table is owned by +Kobako::Sandbox+ and injected
-    # into the per-Sandbox +Kobako::Catalog::Services+ so guest→host dispatch
-    # resolves Handle targets and arguments against the same table that
-    # host→guest wire encoding allocates into.
+    # Each invocation's +Kobako::Context+ mints its own table and hands it to
+    # the dispatcher, so guest→host dispatch resolves Handle targets and
+    # arguments against the same table that host→guest wire encoding allocates
+    # into for that run.
     #
     # Lifecycle invariants:
     #
@@ -17,10 +17,9 @@ module Kobako
     #     invocation is 1; ID 0 is reserved as the invalid sentinel and is
     #     never returned by +#alloc+.
     #
-    #   - At every invocation boundary (via +#reset!+), every Handle issued
-    #     under the old state becomes invalid. Reset applies uniformly
-    #     regardless of allocation source (Service return or host-injected
-    #     argument).
+    #   - A fresh table backs each invocation, so a Handle issued in one
+    #     invocation resolves in no other — uniformly regardless of
+    #     allocation source (Service return or host-injected argument).
     #
     #   - The cap is +0x7fff_ffff+ (2³¹ − 1). Allocation beyond the cap
     #     raises immediately — no silent truncation, no wrap, no ID reuse.
@@ -63,14 +62,6 @@ module Kobako
         @entries[id]
       end
 
-      # Clear all entries AND reset the counter to 1. Called at the
-      # per-invocation boundary by +Kobako::Sandbox+. Returns +self+.
-      def reset!
-        @entries.clear
-        @next_id = 1
-        self
-      end
-
       # Number of currently-bound entries. Used by tests of the Dispatcher
       # and Codec::HandleWalk#deep_wrap to observe whether each path allocates
       # exactly the Handle entries it should — the +Handles+ table itself never

data/lib/kobako/catalog/services.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "handles"
 require_relative "../codec"
 require_relative "../errors"
 
@@ -18,23 +17,19 @@ module Kobako
     #   services.lookup("MyService::KV")           # => kv_object
     #
     # Per-dispatch routing is +Kobako::Transport::Dispatcher+'s
-    # responsibility — the Dispatcher receives this registry and the
-    # +Catalog::Handles+ as arguments from the +Runtime#on_dispatch+ Proc
-    # that +Kobako::Sandbox#initialize+ installs. The registry holds an
-    # injected +Catalog::Handles+ reference so dispatch target resolution
-    # and host→guest auto-wrap share the same Sandbox-owned allocator.
+    # responsibility — the Dispatcher resolves a path against the invocation's
+    # +Kobako::Context+ (which layers per-invocation providers and +ctx.bind+
+    # overrides over these base bindings) and the +Catalog::Handles+, both
+    # passed in the per-invocation dispatch Proc the Context hands to
+    # +Runtime#eval+ / +#run+.
     class Services
       # Ruby constant-name pattern each +::+-separated bind-path segment
       # must match.
       NAME_PATTERN = /\A[A-Z]\w*\z/
 
-      # Build a fresh registry. +handler+ is an internal seam that injects
-      # a pre-configured +Catalog::Handles+; tests pass one whose +next_id+
-      # is pinned near +MAX_ID+ to exercise the cap-exhaustion path
-      # without 2³¹ allocations. Production callers leave it at the default.
-      def initialize(handler: Catalog::Handles.new)
+      # Build a fresh registry.
+      def initialize
         @bindings = {} # : Hash[String, untyped]
-        @handler = handler
         @sealed = false
         @encoded = nil # : String?
       end
@@ -56,6 +51,12 @@ module Kobako
         self
       end
 
+      # Returns +true+ iff a Service is bound at +path+ — the declared (Frame 1)
+      # key set a per-invocation +ctx.bind+ override may target.
+      def bound?(path)
+        @bindings.key?(path.to_s)
+      end
+
       # Resolve a +target+ constant path to the bound Service. Raises
       # +KeyError+ when no Service is bound at +target+.
       def lookup(target)
@@ -65,18 +66,6 @@ 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
@@ -84,23 +73,20 @@ module Kobako
       # Strings, so none of the kobako ext types fire. Returns a binary
       # +String+ of msgpack bytes.
       #
-      # Once sealed, the bytes are computed once and reused for every
-      # subsequent invocation: sealing freezes Service registration at the
-      # first invocation, so a bind reaching the registry after the seal
-      # raises +ArgumentError+ and never alters Frame 1.
+      # The bytes are pinned eagerly by #seal! at the first invocation, so
+      # every subsequent call is a pure read of the frozen preamble — a bind
+      # can never reach the registry after the seal to alter Frame 1.
       def encode
-        return @encoded if @encoded
-
-        bytes = Codec::Encoder.encode(@bindings.keys).freeze
-        @encoded = bytes if @sealed
-        bytes
+        @encoded || Codec::Encoder.encode(@bindings.keys).freeze
       end
 
-      # Mark the registry as sealed. Called by +Sandbox+ on the first
-      # invocation; afterwards #bind raises ArgumentError. Idempotent;
-      # returns +self+.
+      # Mark the registry as sealed and pin the Frame 1 preamble bytes so
+      # registration can never alter them afterwards. Called by +Sandbox+ on
+      # the first invocation; afterwards #bind raises ArgumentError.
+      # Idempotent; returns +self+.
       def seal!
         @sealed = true
+        @encoded ||= Codec::Encoder.encode(@bindings.keys).freeze
         self
       end
 

data/lib/kobako/catalog/snippets.rb

@@ -41,17 +41,19 @@ module Kobako
       # externally via +entry_payload+ rather than asking each entry to
       # self-encode.
       #
-      # The bytes are memoized — the table is replayed verbatim on every
-      # invocation after sealing, so Frame 3 never changes between
-      # encodes; #register drops the memo while the table is still open.
-      # Unlike +Catalog::Services#encode+, which gates its memo on the
-      # seal, this one can fill eagerly and invalidate in +#register+
-      # because every mutation funnels through that single method — there is
-      # no out-of-sight child object to change the result behind its back.
+      # Before the first invocation this recomputes from the still-open
+      # table; #seal! then pins the bytes, so every later call is a pure
+      # read of the frozen memo.
       def encode
-        return @encoded if @encoded
+        @encoded || Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) }).freeze
+      end
 
-        @encoded = Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) }).freeze
+      # Freeze the Frame 3 table bytes at the first invocation so the
+      # replayed snippet set can never change afterwards. Called by +Sandbox+
+      # alongside the Service / Extension seals. Idempotent; returns +self+.
+      def seal!
+        @encoded ||= Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) }).freeze
+        self
       end
 
       # Register one preloaded snippet in either of two forms.
@@ -73,7 +75,6 @@ module Kobako
       # missing keywords, wrong types, malformed +name+, or
       # duplicate +code:+ +name+.
       def register(code: nil, name: nil, binary: nil)
-        @encoded = nil
         if binary
           raise ArgumentError, "cannot combine binary: with code: / name:" if code || name
 

data/lib/kobako/context.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative "capture"
+require_relative "codec"
+require_relative "errors"
+require_relative "execution"
+require_relative "unresolved"
+require_relative "outcome"
+require_relative "usage"
+require_relative "transport"
+require_relative "catalog"
+
+module Kobako
+  # Kobako::Context — the per-invocation driver behind a single +Sandbox#eval+
+  # / +#run+. Each Context owns a fresh +Catalog::Handles+ table and drives one
+  # guest invocation: it builds the dispatch handler, runs the guest, records
+  # the run's captures and usage, and decodes the outcome. One Context per
+  # invocation owns all per-invocation state, so the reusable +Sandbox+ holds
+  # none and overlapping evals never touch each other's state.
+  class Context
+    # Build a Context over the Sandbox-owned config — the +Runtime+, the
+    # sealed +Catalog::Services+ / +Catalog::Snippets+ registries, and the
+    # +Catalog::Extensions+ whose callable backends this Context resolves for
+    # its own run. The +Catalog::Handles+ table is this invocation's own, so
+    # guest→host dispatch and host→guest auto-wrap share one allocator scoped
+    # to the run; the resolved provider map is likewise per-invocation, so
+    # concurrent invocations never share mutable state.
+    def initialize(runtime:, services:, snippets:, extensions:)
+      @runtime = runtime
+      @services = services
+      @snippets = snippets
+      @extensions = extensions
+      @resolved = {} # : Hash[String, untyped]
+      @overrides = {} # : Hash[String, untyped]
+      @spent = false
+      @handler = Catalog::Handles.new
+      @stdout_capture = @stderr_capture = Capture::EMPTY
+      @usage = Usage::EMPTY
+    end
+
+    # Override the object bound at an already-declared +path+ for this
+    # invocation only — the per-eval hook the +#eval+ / +#run+ block uses to
+    # fill a fillable or shadow any static / per-invocation binding. +path+
+    # must name a declared (Frame 1) binding; overriding an undeclared path
+    # raises +ArgumentError+ so the Frame 1 key set stays fixed. Valid only
+    # while the block runs — the Context is spent once the block returns, so a
+    # captured +ctx+ used afterward raises +ArgumentError+ too, putting both
+    # misuses on one rescuable channel. Returns +self+.
+    def bind(path, object)
+      raise ArgumentError, "Kobako::Context is spent; ctx.bind is only valid inside the #eval / #run block" if @spent
+
+      key = path.to_s
+      raise ArgumentError, "cannot override undeclared path #{key.inspect}" unless @services.bound?(key)
+
+      @overrides[key] = object
+      self
+    end
+
+    # Resolve a Service +path+ to the object backing it this invocation,
+    # layering the per-eval +ctx.bind+ overrides over this Context's
+    # per-invocation provider results over the Sandbox's static base bindings.
+    # An unbound path raises +KeyError+; a fillable left unfilled resolves to
+    # +Kobako::Unresolved+ and is reported the same way, so an unresolved
+    # capability fails closed as an undefined target rather than dispatching to
+    # the sentinel. The Dispatcher maps either +KeyError+ to an
+    # undefined-target wire fault. Internal — the per-invocation dispatch
+    # handler is the sole caller.
+    def lookup(path)
+      key = path.to_s
+      object = @overrides.fetch(key) { @resolved.fetch(key) { @services.lookup(path) } }
+      raise KeyError, "service #{path} is declared but unresolved this invocation" if Unresolved.equal?(object)
+
+      object
+    end
+
+    # Execute a guest mruby source string in a fresh +mrb_state+ and return the
+    # decoded last expression. A given +block+ runs first, receiving this
+    # Context to collect +ctx.bind+ overrides before the guest drives.
+    def eval(code, &block)
+      collect_overrides(&block) if block
+      invoke!(:eval) do
+        @runtime.eval(dispatch_handler, @services.encode, code.b, @snippets.encode)
+      end
+    end
+
+    # Dispatch a +Transport::Run+ envelope into a preloaded entrypoint and
+    # return the decoded result. A given +block+ runs first, receiving this
+    # Context to collect +ctx.bind+ overrides before the guest drives.
+    def run(run_envelope, &block)
+      collect_overrides(&block) if block
+      invoke!(:run) do
+        @runtime.run(dispatch_handler, @services.encode, @snippets.encode, run_envelope.encode(@handler))
+      end
+    end
+
+    private
+
+    # Run the per-eval override +block+, handing it this Context so it can call
+    # +ctx.bind+, then spend the Context so a captured +ctx+ used after the
+    # block raises. A block that raises propagates before the guest drives, so
+    # the guest never runs and no Execution is produced.
+    def collect_overrides
+      yield self
+    ensure
+      @spent = true
+    end
+
+    # Build this invocation's guest→host dispatch handler — a +Proc+ routing
+    # each guest→host call through the stateless +Transport::Dispatcher+,
+    # capturing this Context as the path resolver (its +#lookup+ layers the
+    # per-invocation providers over the static bindings) plus +@handler+. Handed to
+    # +Runtime#eval+ / +#run+ as a call argument, so the Runtime holds no
+    # dispatch state and the +Proc+ stays GC-rooted as a live argument for the
+    # synchronous call. 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.
+    def dispatch_handler
+      lambda do |request_bytes, guest_yielder|
+        Transport::Dispatcher.dispatch(request_bytes, self, @handler, guest_yielder)
+      end
+    end
+
+    # Record this invocation's usage and both output captures from the ext
+    # +Snapshot+. Every Snapshot carries them — value return or trap alike — so
+    # +#usage+ / +#stdout+ / +#stderr+ stay readable after a rescued trap.
+    def populate_observability!(snapshot)
+      @usage = Usage.new(wall_time: snapshot.wall_time, memory_peak: snapshot.memory_peak)
+      @stdout_capture = Capture.new(bytes: snapshot.stdout, truncated: snapshot.stdout_truncated?)
+      @stderr_capture = Capture.new(bytes: snapshot.stderr, truncated: snapshot.stderr_truncated?)
+    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+,
+    # so #invoke! can add the verb prefix without erasing the named subclass.
+    def trap_class_for(err)
+      case err
+      when TimeoutError     then TimeoutError
+      when MemoryLimitError then MemoryLimitError
+      else TrapError
+      end
+    end
+
+    # Build the +TrapError+-family exception for a trapped +Snapshot+ from its
+    # neutral trap kind, tagged with the verb — the cap subclasses
+    # (+TimeoutError+ / +MemoryLimitError+) keep their identity, every other
+    # engine fault is the base +TrapError+.
+    def trap_error_for(snapshot, verb)
+      klass = case snapshot.trap_kind
+              when :timeout      then TimeoutError
+              when :memory_limit then MemoryLimitError
+              else TrapError
+              end
+      klass.new("Sandbox##{verb} failed: #{snapshot.trap_message}")
+    end
+
+    # Freeze this run's observables plus +value+ (+nil+ on a failed run) into
+    # the read-only +Execution+ the caller receives or the error carries.
+    # +failed+ records the two apart so a +nil+ +value+ from a successful run
+    # stays distinct from a failed one.
+    def build_execution(value, failed:)
+      Execution.new(value: value, usage: @usage, stdout: @stdout_capture, stderr: @stderr_capture, failed: failed)
+    end
+
+    # Decode a completed run's outcome into its +Execution+. A Capability
+    # Handle in the result is restored to its host object first. Decode sits in
+    # the rescue so a wire-violation trap or a Panic envelope both attach this
+    # run's Execution, just like a guest-call trap does.
+    def settle_outcome(snapshot, verb)
+      value, carried = Codec.track_handles { Outcome.decode(snapshot.outcome) }
+      value = Codec::HandleWalk.deep_restore(value, @handler) if carried
+      build_execution(value, failed: false)
+    rescue Kobako::TrapError => e
+      raise trap_class_for(e).new("Sandbox##{verb} failed: #{e.message}").with_execution(build_execution(nil,
+                                                                                                         failed: true))
+    rescue Kobako::SandboxError, Kobako::ServiceError => e
+      raise e.with_execution(build_execution(nil, failed: true))
+    end
+
+    # Drive one invocation and settle it into a frozen +Execution+. +verb+
+    # tags the TrapError message so the failing export is identifiable. This
+    # invocation's callable Extension backends are resolved first — before the
+    # guest runs — so a provider that raises propagates unwrapped and leaves
+    # the guest unrun. Usage and captures are recorded before the trap check,
+    # so a trapped Snapshot's error carries them just like a completed run's
+    # return value. A could-not-start fault ran no invocation at all, so it
+    # carries no Execution and gains only the verb prefix.
+    def invoke!(verb)
+      @resolved = @extensions.resolve
+      begin
+        snapshot = yield
+      rescue Kobako::TrapError => e
+        raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
+      end
+      populate_observability!(snapshot)
+      return settle_outcome(snapshot, verb) unless snapshot.trapped?
+
+      raise trap_error_for(snapshot, verb).with_execution(build_execution(nil, failed: true))
+    end
+  end
+end