kobako 0.14.0 → 0.16.0

data/lib/kobako/codec/ext_types.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+require_relative "error"
+require_relative "utils"
+require_relative "state"
+require_relative "../handle"
+require_relative "../fault"
+
+module Kobako
+  module Codec
+    # The kobako wire ext-type conversions
+    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types)
+    # as pure functions: per-operation decode state is threaded in as an
+    # argument, so the module itself holds nothing. #build_factory assembles
+    # the one +MessagePack::Factory+ these conversions are registered on.
+    module ExtTypes
+      # MessagePack ext type code reserved for Symbol
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
+      # → ext 0x00). Module-private — mirrors +codec::EXT_SYMBOL+ on the
+      # Rust side.
+      EXT_SYMBOL = 0x00
+      # MessagePack ext type code reserved for Capability Handle
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
+      # → ext 0x01). Module-private — mirrors +codec::EXT_HANDLE+ on the
+      # Rust side.
+      EXT_HANDLE = 0x01
+      # MessagePack ext type code reserved for Exception envelope
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
+      # → ext 0x02). Module-private — mirrors +codec::EXT_ERRENV+ on the
+      # Rust side.
+      EXT_ERRENV = 0x02
+      private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
+
+      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.
+      def build_factory
+        factory = MessagePack::Factory.new
+        register_symbol(factory)
+        register_handle(factory)
+        register_fault(factory)
+        factory.freeze
+      end
+
+      # Symbol-to-name packer for the ext-0x00 registration.
+      def pack_symbol(symbol)
+        symbol.name
+      end
+
+      # Validate the ext-0x00 payload as UTF-8 and intern. Raises
+      # InvalidEncoding on invalid bytes — SPEC forbids the
+      # binary-encoding fallback that msgpack-gem's default unpacker
+      # would otherwise apply. The re-tag step lives here because the
+      # msgpack ext-type unpacker hands us binary bytes; the assertion
+      # itself is shared with Decoder via Utils.assert_utf8!. The
+      # +"Symbol"+ label keeps the error message in Ruby vocabulary
+      # rather than wire-ext-code vocabulary.
+      def unpack_symbol(payload)
+        name = payload.b.force_encoding(Encoding::UTF_8)
+        Utils.assert_utf8!(name, "Symbol payload")
+        name.to_sym
+      end
+
+      # Handle-id packer for the ext-0x01 registration: the fixext-4
+      # big-endian id frame.
+      def pack_handle(handle)
+        [handle.id].pack("N")
+      end
+
+      # Peel off the fixext-4 frame, hand the bytes to the
+      # Host-Gem-internal +Kobako::Handle.restore+ factory, and
+      # translate the +ArgumentError+ raised by Handle's invariants
+      # into a wire-layer +InvalidType+ via Codec::Utils.with_boundary.
+      # The Value Object owns the id-range contract; this method only
+      # owns the frame shape. Records the Handle sighting on +state+ so a
+      # Handle-free decode can skip the downstream resolution walk.
+      def unpack_handle(payload, state)
+        state.record_handle!
+        bytes = payload.b
+        raise InvalidType, "Handle payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
+
+        id = bytes.unpack1("N") # : Integer
+        Codec::Utils.with_boundary { Kobako::Handle.restore(id) }
+      end
+
+      # Encode the inner ext-0x02 map via Encoder (not the raw factory) so
+      # the embedded payload flows through the same boundary as a top-level
+      # encode — nested kobako values (Handle, nested Fault) reach the
+      # registered ext-type packers. A +details+ chain nested past the
+      # +state+ depth cap has no wire representation and surfaces as
+      # +UnsupportedType+. In a payload position (+state+ inside a
+      # forbid_faults bracket) the envelope has no wire representation at
+      # all, so the refusal routes the value into the position's
+      # non-representable handling — the Dispatcher's auto-wrap rescue,
+      # or a raise at the yield site.
+      def pack_fault(fault, state)
+        if state.faults_forbidden?
+          raise UnsupportedType, "Kobako::Fault has no wire representation in a payload position"
+        end
+
+        state.within_ext_frame(UnsupportedType) do
+          Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
+        end
+      end
+
+      # Peel the embedded msgpack map and hand it to +Kobako::Fault.new+
+      # inside Decoder.decode's block form, so the value-object's
+      # +ArgumentError+ invariants surface as +InvalidType+ through the
+      # decoder boundary. Inner decode goes through Decoder (not the raw
+      # factory) so the embedded +str+ payloads flow through the same
+      # UTF-8 validation as a top-level decode. A nested ext 0x02 in
+      # +details+ re-enters this method, so the +state+ ext-frame guard
+      # bounds the chain depth to keep it from exhausting the native stack.
+      # In a payload position (+state+ inside a forbid_faults bracket) the
+      # envelope is a wire violation outright — its sole legal position is
+      # the Response fault field.
+      def unpack_fault(payload, state)
+        if state.faults_forbidden?
+          raise InvalidType, "Fault envelope (ext 0x02) is not a legal value in a payload position"
+        end
+
+        state.within_ext_frame(InvalidType) do
+          Decoder.decode(payload) do |map|
+            raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
+
+            Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
+          end
+        end
+      end
+
+      def register_symbol(factory)
+        factory.register_type(
+          EXT_SYMBOL, Symbol,
+          packer: ->(symbol) { ExtTypes.pack_symbol(symbol) },
+          unpacker: ->(payload) { ExtTypes.unpack_symbol(payload) }
+        )
+      end
+
+      def register_handle(factory)
+        factory.register_type(
+          EXT_HANDLE, Kobako::Handle,
+          packer: ->(handle) { ExtTypes.pack_handle(handle) },
+          unpacker: ->(payload) { ExtTypes.unpack_handle(payload, State.current) }
+        )
+      end
+
+      def register_fault(factory)
+        factory.register_type(
+          EXT_ERRENV, Kobako::Fault,
+          packer: ->(fault) { ExtTypes.pack_fault(fault, State.current) },
+          unpacker: ->(payload) { ExtTypes.unpack_fault(payload, State.current) }
+        )
+      end
+    end
+
+    # The process-wide registered factory: ext registration is paid once at
+    # load, and a registered +MessagePack::Factory+ only reads its type
+    # registry afterwards, so every thread shares this instance for byte
+    # work.
+    FACTORY = ExtTypes.build_factory
+    private_constant :FACTORY
+  end
+end

data/lib/kobako/codec/state.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Codec
+    # Codec-internal, per-thread state of the operation in flight: the
+    # ext-envelope nesting depth and whether a Capability Handle crossed
+    # the current decode. Thread scoping is what makes plain instance
+    # variables sound — host codec calls run synchronously on their
+    # owning thread, and a nested decode (an ext 0x02 Fault re-entering
+    # through its +details+) reuses the same thread instance, so the
+    # depth counter accumulates across the re-entry instead of resetting.
+    class State
+      # An ext 0x02 (Fault) envelope nests through its +details+ field, and
+      # each level re-enters the codec with a fresh +MessagePack+ unpacker
+      # whose built-in stack guard resets — so ext-envelope depth is tracked
+      # here instead. The cap matches the wire's overall nesting bound and
+      # keeps a nested chain from exhausting the native stack: an over-deep
+      # chain fails as a clean wire error, never a stack-level trap.
+      MAX_EXT_DEPTH = 128
+      private_constant :MAX_EXT_DEPTH
+
+      # Thread-local slot holding the calling thread's State.
+      STATE_KEY = :__kobako_codec_state__
+      private_constant :STATE_KEY
+
+      # The calling thread's State, built on first use so the mutable
+      # state stays isolated to the thread that runs the codec call.
+      def self.current
+        Thread.current[STATE_KEY] ||= new
+      end
+      private_class_method :new
+
+      def initialize
+        @ext_depth = 0
+        @carried_handle = false
+        @faults_forbidden = false
+      end
+
+      # Bracket a decode and return the block's result together with
+      # whether the decoded tree carried an ext 0x01 Capability Handle.
+      # ExtTypes#unpack_handle is the sole chokepoint every Handle passes
+      # through, so one decode pass records the whole tree and a caller
+      # can skip an all-identity Handle-resolution walk when none was
+      # present.
+      def track_handles
+        @carried_handle = false
+        result = yield
+        [result, @carried_handle]
+      end
+
+      # Record that an ext 0x01 Capability Handle crossed the current
+      # decode; #track_handles reports it to the bracketing caller.
+      def record_handle!
+        @carried_handle = true
+      end
+
+      # Bracket a codec operation in a payload position, where an ext 0x02
+      # Fault envelope has no legal wire representation: the fault field of
+      # an error Response is its only home. The ext-type conversions
+      # consult #faults_forbidden? and refuse the envelope in both
+      # directions while the bracket is open. Save/restore keeps a nested
+      # legal operation on the same thread unaffected.
+      def forbid_faults
+        previous = @faults_forbidden
+        @faults_forbidden = true
+        yield
+      ensure
+        @faults_forbidden = previous
+      end
+
+      # Whether the operation in flight sits inside a #forbid_faults
+      # bracket — i.e. in a payload position where ext 0x02 is a wire
+      # violation.
+      def faults_forbidden?
+        @faults_forbidden
+      end
+
+      # Track ext-envelope re-entry depth and refuse a chain past
+      # MAX_EXT_DEPTH, raising +over_limit+ so the failure lands in the
+      # caller's existing wire-error class. The next depth is checked before
+      # it is committed, so an over-deep rejection leaves the counter
+      # untouched, and the +ensure+ restores the entry value on the way out.
+      def within_ext_frame(over_limit)
+        depth = @ext_depth + 1
+        raise over_limit, "ext envelope nesting exceeds #{MAX_EXT_DEPTH} levels" if depth > MAX_EXT_DEPTH
+
+        @ext_depth = depth
+        begin
+          yield
+        ensure
+          @ext_depth = depth - 1
+        end
+      end
+    end
+
+    private_constant :State
+  end
+end

data/lib/kobako/codec/utils.rb

@@ -10,7 +10,7 @@ module Kobako
     #   - UTF-8 assertion at the codec boundary
     #     ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
     #     § str/bin Encoding Rules and § Ext Types → ext 0x00). Used by
-    #     Decoder when walking +str+ family payloads and by Factory
+    #     Decoder when walking +str+ family payloads and by ExtTypes
     #     when validating the +ext 0x00+ Symbol payload.
     #   - +ArgumentError+ translation at the codec boundary
     #     (#with_boundary) so the public taxonomy stays
@@ -38,7 +38,7 @@ module Kobako
       #
       # Reach for this only where a value object is constructed outside a
       # Decoder.decode block, whose rescue already performs the same
-      # mapping (worked example: Factory#unpack_handle building
+      # mapping (worked example: ExtTypes#unpack_handle building
       # +Handle.restore+ from a raw fixext payload). Do not use it for
       # general-purpose validation outside the codec boundary —
       # host-layer +ArgumentError+ values should propagate unchanged.

data/lib/kobako/codec.rb

@@ -3,7 +3,8 @@
 require_relative "codec/error"
 require_relative "codec/utils"
 require_relative "codec/handle_walk"
-require_relative "codec/factory"
+require_relative "codec/state"
+require_relative "codec/ext_types"
 require_relative "codec/encoder"
 require_relative "codec/decoder"
 
@@ -18,14 +19,30 @@ module Kobako
   # the kobako root so the codec can register them without depending
   # upward on Transport.
   #
-  # Backed by the official +msgpack+ gem via Factory; Encoder and
-  # Decoder are thin wrappers that register the three kobako-specific
-  # ext types (0x00 Symbol, 0x01 Capability Handle, 0x02 Exception
-  # envelope) on a single +MessagePack::Factory+ instance. The Rust side
+  # Backed by the official +msgpack+ gem: ExtTypes registers the three
+  # kobako-specific ext types (0x00 Symbol, 0x01 Capability Handle,
+  # 0x02 Exception envelope) on one process-wide +MessagePack::Factory+,
+  # and Encoder / Decoder are thin wrappers over it. The Rust side
   # mirrors this layer as the +codec+ module in the +kobako-codec+ crate;
-  # the ext-code constants live as module-private values on Factory
+  # the ext-code constants live as module-private values on ExtTypes
   # alongside +codec::EXT_SYMBOL+ / +codec::EXT_HANDLE+ /
   # +codec::EXT_ERRENV+ on that side.
   module Codec
+    # 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.
+    # The tracking state is codec-internal; this is its only readout.
+    def self.track_handles(&block)
+      State.current.track_handles(&block)
+    end
+
+    # Bracket a codec operation in a payload position: an ext 0x02 Fault
+    # envelope is only legal in the Response fault field, so the envelope
+    # layers open this bracket around every other encode / decode and the
+    # ext-type conversions refuse the envelope while it is open — a wire
+    # violation on decode, no wire representation on encode.
+    def self.forbid_faults(&block)
+      State.current.forbid_faults(&block)
+    end
   end
 end

data/lib/kobako/extension.rb

@@ -0,0 +1,47 @@
+# 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.
+    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/fault.rb

@@ -5,7 +5,7 @@ module Kobako
   #
   # Top-level shared wire primitive: like +Kobako::Handle+ (ext 0x01),
   # +Fault+ is a MessagePack ext-type leaf registered by
-  # +Kobako::Codec::Factory+ and rides nested inside other envelopes (a
+  # +Kobako::Codec::ExtTypes+ and rides nested inside other envelopes (a
   # +Kobako::Transport::Response+ error payload, or another Fault's
   # +details+). It lives at the kobako root rather than under +Transport+
   # because the Codec layer must register it, and Codec must not depend

data/lib/kobako/handle.rb

@@ -18,7 +18,7 @@ module Kobako
   # constructor — is removed for the same reason: a legitimate Handle
   # must not derive a sibling with a caller-chosen id. The Host Gem itself constructs
   # Handles through +.restore+, which exists at exactly two call
-  # sites: +Kobako::Codec::Factory#unpack_handle+ (wire decode) and
+  # sites: +Kobako::Codec::ExtTypes#unpack_handle+ (wire decode) and
   # +Kobako::Codec::HandleWalk.deep_wrap+ / +Kobako::Transport::Dispatcher#wrap_as_handle+
   # (allocator paths). Both live inside +lib/kobako/+ and are not part
   # of any public surface.

data/lib/kobako/outcome.rb

@@ -70,7 +70,9 @@ module Kobako
     # "Symbol payload must be …" wording, but operators triaging a
     # corrupted Sandbox runtime still need it.
     def decode_value(body)
-      Kobako::Codec::Decoder.decode(body)
+      # The Result envelope is a payload position: an ext 0x02 Fault in it
+      # is a wire violation routed into the invalid-result rescue below.
+      Kobako::Codec.forbid_faults { Kobako::Codec::Decoder.decode(body) }
     rescue Kobako::Codec::Error => e
       raise build_transport_error(
         "Sandbox produced an invalid result value",
@@ -99,13 +101,17 @@ module Kobako
     # through the decoder boundary; the message itself is never user-
     # facing — it lands in +details+ via the rescue chain above.
     def build_panic_record(body)
-      Kobako::Codec::Decoder.decode(body) do |map|
-        raise Kobako::Codec::InvalidType, "panic body must be a map, got #{map.class}" unless map.is_a?(Hash)
+      # The Panic envelope is a payload position: an ext 0x02 Fault in its
+      # +details+ is a wire violation routed into the invalid-panic rescue.
+      Kobako::Codec.forbid_faults do
+        Kobako::Codec::Decoder.decode(body) do |map|
+          raise Kobako::Codec::InvalidType, "panic body must be a map, got #{map.class}" unless map.is_a?(Hash)
 
-        Panic.new(
-          origin: map["origin"], klass: map["class"], message: map["message"],
-          backtrace: map["backtrace"] || [], details: map["details"]
-        )
+          Panic.new(
+            origin: map["origin"], klass: map["class"], message: map["message"],
+            backtrace: map["backtrace"] || [], details: map["details"]
+          )
+        end
       end
     end
 

data/lib/kobako/pool.rb

@@ -24,7 +24,7 @@ module Kobako
     # seconds (+nil+ waits indefinitely); every other keyword is
     # forwarded verbatim to +Kobako::Sandbox.new+. The optional block
     # runs exactly once per constructed Sandbox — it is the setup window
-    # for +#define+ / +#preload+ before that Sandbox's first checkout.
+    # for +#bind+ / +#preload+ before that Sandbox's first checkout.
     # No Sandbox is constructed here. Raises +ArgumentError+ for an
     # invalid +slots+ / +checkout_timeout+.
     def initialize(slots:, checkout_timeout: DEFAULT_CHECKOUT_TIMEOUT_SECONDS, **sandbox_options, &setup)

data/lib/kobako/sandbox.rb

@@ -17,7 +17,7 @@ module Kobako
   #
   # The Sandbox owns the +Kobako::Runtime+, the per-Sandbox
   # +Kobako::Catalog::Handles+, the per-instance
-  # +Kobako::Catalog::Namespaces+ (which receives the +Catalog::Handles+ by
+  # +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
@@ -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
@@ -100,21 +92,42 @@ module Kobako
       @wasm_path = wasm_path || Kobako::Runtime.default_path
       @options = SandboxOptions.new(**)
       @handler = Catalog::Handles.new
-      @services = Kobako::Catalog::Namespaces.new(handler: @handler)
+      @services = Kobako::Catalog::Services.new(handler: @handler)
       @snippets = Catalog::Snippets.new
+      @extensions = Catalog::Extensions.new
       @runtime = build_runtime!
       install_dispatch_proc!
       reset_invocation_state!
     end
 
-    # Declare or retrieve the Namespace named +name+ on this Sandbox. +name+
-    # must be a Symbol or String in constant form. Returns the
-    # +Kobako::Namespace+.
+    # Bind +object+ as the Service reachable at +path+ — a Symbol or
+    # String of one or more +::+-separated constant-form segments
+    # (+"MyService::KV"+ or a top-level +"File"+). Returns +self+ for
+    # chaining.
+    #
+    # 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)
+      @services.bind(path, object)
+      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+ when called after the first invocation, or
-    # when +name+ does not match the constant-name pattern.
-    def define(name)
-      @services.define(name)
+    # 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:
@@ -175,15 +188,15 @@ module Kobako
     #
     # Source delivery uses the WASI stdin three-frame protocol
     # ({docs/wire-codec.md Invocation channels}[link:../../docs/wire-codec.md]):
-    # Frame 1 carries the msgpack-encoded preamble (Namespace / Member
-    # registry snapshot), Frame 2 carries the user source UTF-8 bytes, and
+    # Frame 1 carries the msgpack-encoded preamble (Service registry
+    # snapshot), Frame 2 carries the user source UTF-8 bytes, and
     # Frame 3 carries the snippet table registered via +#preload+.
     # Each frame is prefixed by a 4-byte big-endian u32 length; Frame 3 is
     # mandatory-presence — an empty snippet table sends an empty msgpack
     # array, never an absent frame.
     #
     # The first invocation seals the Service registry and snippet table;
-    # subsequent +#define+ / +#preload+ calls raise +ArgumentError+.
+    # subsequent +#bind+ / +#preload+ calls raise +ArgumentError+.
     #
     # Raises +Kobako::TrapError+ on a Wasm trap or wire-violation fallback;
     # +Kobako::SandboxError+ when the guest ran to completion but failed
@@ -237,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
@@ -318,7 +335,10 @@ module Kobako
       # 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!.
-      Codec::HandleWalk.deep_restore(Outcome.decode(return_bytes), @handler)
+      # 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