kobako 0.27.0 → 0.29.0

data/lib/kobako/transport/reflection.rb

@@ -2,26 +2,7 @@
 
 module Kobako
   module Transport
-    # The reflection floor a guest→host dispatch must clear before the
-    # Dispatcher reaches +public_send+: which method names on a resolved
-    # target count as Service behaviour, and which are Ruby's ambient
-    # metaprogramming surface.
-    #
-    # Answers with a refusal reason rather than raising, so the error
-    # taxonomy stays with the Dispatcher and this module holds only the
-    # policy.
-    module Reflection
-      # Modules whose instance methods are ambient Ruby reflection /
-      # metaprogramming surface (+send+, +public_send+, +instance_eval+,
-      # +method+, +tap+, +instance_variable_get+, ...) rather than Service
-      # behaviour. A guest-supplied method name resolving to one of these is
-      # rejected: only methods the bound object itself exposes as Service
-      # behaviour are reachable, and +public_send(:send, ...)+ would
-      # otherwise let a guest pivot through +send+ into the private
-      # +Kernel#eval+ / +#system+ surface (host RCE).
-      META_OWNERS = [BasicObject, Kernel, Object, Module, Class].freeze
-      private_constant :META_OWNERS
-
+    module Reflection # :nodoc:
       # Callable gadget types whose own public methods are reflection surface
       # (+Proc#binding+ reaches +Binding#eval+, +Method#receiver+ / +#unbind+
       # hand back the underlying object) rather than Service behaviour. Only
@@ -36,59 +17,123 @@ module Kobako
       # callable exposes by default, so the floor and the Exposure agree.
       CALLABLE_ALLOW = %i[call [] yield arity lambda?].freeze
 
-      module_function
-
       # The reason +name+ is unreachable through +exposure+, or +nil+ when
       # the dispatch may proceed. Composes the ambient-surface floor with the
       # reference's Exposure, in that order: the Exposure only narrows and
       # can never re-open what the floor rejects.
-      def refusal(exposure, name)
+      def self.refusal(exposure, name)
         ambient_refusal(exposure.object, name) ||
           (exposure.exposes?(name) ? nil : "method #{name.inspect} is not exposed to the guest")
       end
 
-      # Guard against ambient reflection methods. A public method whose
-      # owner is a META_OWNERS or GADGET_OWNERS module — or a singleton
-      # class, the owner of every class-level method (+File.popen+ /
-      # +Kernel.system+, unreachable via any fixed core-module list) — is
-      # rejected, except CALLABLE_ALLOW on a gadget target (a bound lambda
-      # stays invocable). A name with no concrete public method is allowed
-      # only when the target opts into it via +respond_to?+ (dynamic
-      # +method_missing+ Services), since the dangerous methods are all
-      # concretely defined and therefore never reach that branch.
-      #
-      # +method_missing+ named explicitly is refused whatever its owner:
-      # it is Ruby's dynamic-dispatch hook, and a public override (a
-      # +Delegator+) binds and calls the private method the guest passes as
-      # its first argument (+Kernel#system+). A dynamic +method_missing+
-      # Service is untouched — the guest reaches it by the virtual name,
-      # which resolves through the +NameError+ branch below, never by
-      # naming +method_missing+.
-      def ambient_refusal(target, name)
-        return "method #{name.inspect} is not a Service method" if name == :method_missing
-
-        owner = target.public_method(name).owner
-        return nil unless ambient_owner?(owner, target)
-        return nil if GADGET_OWNERS.include?(owner) && CALLABLE_ALLOW.include?(name)
-
-        "method #{name.inspect} is not a Service method"
-      rescue NameError
-        return nil if target.respond_to?(name)
-
-        "no public method #{name.inspect} on target"
+      # Whether +method+ is written in Ruby rather than built into the
+      # platform or copied from the surface every object shares. A native
+      # method has no source, and a built-in one names an +<internal:>+ file,
+      # so a copy, alias or rebinding of either keeps that mark wherever it
+      # is reached from.
+      def self.authored?(method)
+        file, = method.source_location
+        !file.nil? && !file.start_with?("<internal:") && !ambient_copy?(method)
       end
 
-      # Whether +name+'s +owner+ is ambient surface rather than Service
-      # behaviour: a core meta module, a callable gadget type, or — when
-      # +target+ is itself a Class or Module bound as a Service — the
-      # singleton class that owns its class-level API (+File.popen+ /
-      # +Kernel.system+, unreachable via any fixed core-module list). A plain
-      # object's own singleton method (+def obj.x+) stays reachable, since
-      # +target+ is not a Module there.
-      def ambient_owner?(owner, target)
-        META_OWNERS.include?(owner) ||
-          GADGET_OWNERS.include?(owner) ||
-          (target.is_a?(Module) && owner.singleton_class?)
+      class << self
+        private
+
+        # Whether +method+ is a copy, alias or rebinding of a Ruby method
+        # +Class+ inherits, such as the +name!+ alias OpenStruct makes of a
+        # mixed-in +try+. The copy is owned by the class that made it, but
+        # keeps the original's name and source.
+        def ambient_copy?(method)
+          name = method.original_name
+          Class.ancestors.any? do |owner|
+            (owner.method_defined?(name, false) || owner.private_method_defined?(name, false)) &&
+              owner.instance_method(name).source_location == method.source_location
+          end
+        end
+
+        # Guard against ambient reflection methods. A public method whose
+        # owner +Class+ inherits or a GADGET_OWNERS module — or a singleton
+        # class, the owner of every class-level method (+File.popen+ /
+        # +Kernel.system+, unreachable via any fixed core-module list) — is
+        # rejected, except CALLABLE_ALLOW on a gadget target (a bound lambda
+        # stays invocable). A name with no concrete public method is allowed
+        # only when the target opts into it via +respond_to?+ (dynamic
+        # +method_missing+ Services), since the dangerous methods are all
+        # concretely defined and therefore never reach that branch.
+        #
+        # +method_missing+ named explicitly is refused whatever its owner:
+        # it is Ruby's dynamic-dispatch hook, and a public override (a
+        # +Delegator+) binds and calls the private method the guest passes as
+        # its first argument (+Kernel#system+). A dynamic +method_missing+
+        # Service is untouched — the guest reaches it by the virtual name,
+        # which resolves through the +respond_to?+ opt-in, never by naming
+        # +method_missing+.
+        #
+        # A public method must also be authored, so a Service narrowing itself
+        # never reaches a built-in or ambient method by a copy, alias or
+        # rebinding an owner check cannot see; a non-public one is never
+        # reached through a dynamic opt-in either.
+        #
+        # A name with no method never reaches +instance_method+, which would
+        # keep a guest-chosen name as a Symbol for the life of the process.
+        def ambient_refusal(target, name)
+          return refused(name) if name == :method_missing
+
+          klass = lookup_class(target)
+          return defined_refusal(target, name, klass) if klass.public_method_defined?(name)
+          return "no public method #{name.inspect} on target" unless target.respond_to?(name)
+          return refused(name) if klass.method_defined?(name) || klass.private_method_defined?(name)
+
+          owner_refusal(target, name, klass)
+        end
+
+        def defined_refusal(target, name, klass)
+          method = klass.instance_method(name)
+          owner_refusal(target, name, method.owner) ||
+            (authored_for?(target, name, method, klass) ? nil : refused(name))
+        end
+
+        # A bound callable keeps its callable names and a record its member
+        # readers, though the platform defines both.
+        def authored_for?(target, name, method, klass)
+          return true if Reflection.authored?(method)
+          return true if GADGET_OWNERS.include?(method.owner) && CALLABLE_ALLOW.include?(name)
+
+          (klass <= Struct || klass <= Data) && target.members.include?(name)
+        end
+
+        def refused(name)
+          "method #{name.inspect} is not a Service method"
+        end
+
+        def owner_refusal(target, name, owner)
+          return nil unless ambient_owner?(owner, target)
+          return nil if GADGET_OWNERS.include?(owner) && CALLABLE_ALLOW.include?(name)
+
+          refused(name)
+        end
+
+        # The class a method lookup on +target+ starts at. A plain object's
+        # singleton class is taken only when it already holds a public
+        # method, since asking for it otherwise would create one.
+        def lookup_class(target)
+          return target.singleton_class if target.is_a?(Module) || target.singleton_methods.any?
+
+          target.class
+        end
+
+        # Whatever +Class+ inherits is surface every object shares rather
+        # than Service behaviour: the reflection +BasicObject+ through +Class+
+        # define (+send+ pivots into +Kernel#eval+, a host RCE), and every
+        # module a library mixes into them, such as a +try+ dispatching by
+        # name or a +to_json+ dumping instance variables. A plain object's
+        # own singleton method (+def obj.x+) stays reachable, since only a
+        # Module target counts its singleton class as ambient.
+        def ambient_owner?(owner, target)
+          owner >= Class ||
+            GADGET_OWNERS.include?(owner) ||
+            (target.is_a?(Module) && owner.singleton_class?)
+        end
       end
     end
   end

data/lib/kobako/transport/run.rb

@@ -1,44 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../constant_name"
 require_relative "../handle"
 require_relative "../codec"
 require_relative "../payload"
 
 module Kobako
-  # See lib/kobako/transport.rb for the umbrella module doc; this file
-  # owns +Run+, the host-side value object for one +#run+ request — the
-  # native side frames it into the envelope +__kobako_run+ consumes.
   module Transport
-    # Host-side value object for a single +Sandbox#run+ invocation
-    # ({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 (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 ship to the guest.
-    #
-    # +#payload+ takes the invocation's +Catalog::Handles+ and routes any
-    # non-wire-representable +args+ / +kwargs+ leaf through it as a
-    # +Kobako::Handle+ — the symmetric counterpart of the guest→host wrap
-    # path in the dispatcher. A +Kobako::Handle+ that arrives **already
-    # constructed** in the caller's +args+ / +kwargs+ is rejected at
-    # construction: legitimate Handles only enter Host App code through
-    # error fields, so a Handle reaching the call site is by definition
-    # smuggled in. +Runtime#run+ frames that payload with the entrypoint
-    # into the Run envelope the +__kobako_run+ command buffer carries.
-    #
-    # Built on the +class X < Data.define(...)+ subclass form (the
-    # Steep-friendly shape — see +.rubocop.yml+ for the rationale).
-    class Run < Data.define(:entrypoint, :args, :kwargs)
-      # 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.
-      NAME_PATTERN = /\A[A-Z]\w*\z/
-
+    # A Handle already in the arguments is refused, since a caller never
+    # legitimately holds one.
+    class Run < Data.define(:entrypoint, :args, :kwargs) # :nodoc:
       def initialize(entrypoint:, args: [], kwargs: {})
         entrypoint = normalize_entrypoint(entrypoint)
         validate_args!(args)
@@ -46,61 +17,42 @@ module Kobako
         super
       end
 
-      # Encode this Run's arguments as the codec payload the Run
-      # envelope carries — +Runtime#run+ frames it with the entrypoint.
-      # Walks +args+ / +kwargs+ through Codec::HandleWalk.deep_wrap so
-      # any non-wire-representable leaf is allocated into +handler+ and
-      # replaced with a +Kobako::Handle+; the +handler+ argument is the
-      # invocation's table, sharing the same allocator the guest→host
-      # return path uses. A wrapped leaf rides as ext 0x01 in its
-      # original position (docs/wire/payload-msgpack.md § ext 0x01).
-      # The walk starts one level down, since +args+ and +kwargs+ ride
-      # inside the payload document the wire's nesting bound is counted
-      # from.
-      def payload(handler)
+      # A leaf with no wire form becomes a Capability Handle in the
+      # invocation's table. The walk starts one level down, since +args+ and
+      # +kwargs+ ride inside the payload document the wire's nesting bound
+      # is counted from.
+      def payload(handles)
         Payload::Arguments.new(
-          args: Codec::HandleWalk.deep_wrap(args, handler, 1),
-          kwargs: Codec::HandleWalk.deep_wrap(kwargs, handler, 1)
+          args: Codec::HandleWalk.deep_wrap(args, handles, 1),
+          kwargs: Codec::HandleWalk.deep_wrap(kwargs, handles, 1)
         ).encode
       end
 
       private
 
-      # 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). After +.to_s+
-      # the value must match NAME_PATTERN (ArgumentError), rejecting
-      # +::+-segmented names and any non-constant form.
+      # A target of the wrong type raises TypeError, a Host App programming
+      # error caught before the run reaches the guest.
       def normalize_entrypoint(target)
         unless target.is_a?(Symbol) || target.is_a?(String)
           raise TypeError, "entrypoint must be a Symbol or String, got #{target.class}"
         end
 
         target_str = target.to_s
-        unless NAME_PATTERN.match?(target_str)
+        unless CONSTANT_NAME.match?(target_str)
           raise ArgumentError,
-                "entrypoint must match #{NAME_PATTERN.inspect} (got #{target.inspect})"
+                "entrypoint must match #{CONSTANT_NAME.inspect} (got #{target.inspect})"
         end
 
         target_str.to_sym
       end
 
-      # +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 +#payload+ — 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)
         raise ArgumentError, forged_handle_message("arguments") if args.any?(Kobako::Handle)
       end
 
-      # 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.
+      # Checked here so the Host App sees the host-side message before any
+      # encode boundary.
       def validate_kwargs!(kwargs)
         raise ArgumentError, "keyword arguments must be a Hash" unless kwargs.is_a?(Hash)
 
@@ -112,12 +64,6 @@ module Kobako
         raise ArgumentError, forged_handle_message("keyword argument values") if kwargs.each_value.any?(Kobako::Handle)
       end
 
-      # 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 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)
         "#{slot} must not contain a Kobako::Handle — " \
           "Handles are created internally by the Sandbox and cannot be passed in"

data/lib/kobako/transport/yielder.rb

@@ -4,101 +4,43 @@ require_relative "../codec"
 require_relative "../errors"
 
 module Kobako
-  # See lib/kobako/transport.rb for the umbrella module doc; this file
-  # 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.
-    #
-    # 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, and reifies the Yield Reply into Ruby
-    # control flow:
-    #
-    #   * ok    — return the decoded value to +yield+'s caller
-    #   * break — +throw break_tag, value+ so the Dispatcher's +catch+
-    #     frame unwinds the Service method
-    #   * error — raise a BlockError at the Service's yield site,
-    #     carrying the guest's class on +#klass+
-    #
-    # 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 an escaped Yielder.
-    class Yielder
-      # +yield_to_guest+ is the ext's per-dispatch
-      # +Kobako::Runtime::GuestYielder+, which #yield invokes to re-enter
-      # the guest: it takes the argument payload and answers the reply
-      # already split into +[arm, body, class]+. +break_tag+ is the
-      # +catch+ throw tag the Dispatcher matches against to unwind the
-      # Service on a break. +handler+ is the invocation'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.
-      def initialize(yield_to_guest, break_tag, handler)
-        @yield_to_guest = yield_to_guest
+    class Yielder # :nodoc:
+      def initialize(guest_yielder, break_tag, handles, failure)
+        @guest_yielder = guest_yielder
         @break_tag = break_tag
-        @handler = handler
+        @handles = handles
+        @failure = failure
         @active = true
-        @raised = nil
       end
 
-      # The text the guest's own block failure crosses back as, or +nil+
-      # when +error+ is not the BlockError this Yielder raised. Identity
-      # rather than class: a Service that rescued the block's failure and
-      # raised its own has reported something else, and the guest must
-      # hear about that instead.
-      #
-      # The class travels with the message because not every block failure
-      # is an exception the guest holds — a block value the guest refused
-      # has a class to raise under and no object to continue.
-      def fault_text(error)
-        raised = @raised
-        return if raised.nil? || !error.equal?(raised)
-
-        "#{raised.klass}: #{raised.message}"
-      end
-
-      # Re-enter the guest with +args+ and reify the Yield Reply into
-      # Ruby control flow. Raises +LocalJumpError+ if called after
-      # #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
-      # 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.
+      # The ok value is consumed by the host Service, so a Capability Handle
+      # in it is restored. A block exit stays in the guest, so the Service
+      # is only unwound.
       def yield(*args)
         raise LocalJumpError, "guest block invoked after host dispatch frame returned" unless @active
 
-        arm, body, klass = @yield_to_guest.call(encode_args(args))
-        raise remember(BlockError.new(body, klass: klass)) if arm == :error
+        arm, body, klass = @guest_yielder.call(encode_args(args))
+        raise UnsupportedError, "the Sandbox runtime does not support yielding to a block" if arm == :unsupported
+        raise @failure.remember(BlockError.new(body, klass: klass)) if arm == :error
 
-        value, carried_handle = decode_body(body)
-        throw @break_tag, value if arm == :break
+        throw @break_tag if arm == :break
 
-        restore(value, carried_handle)
+        restore(*decode_body(body))
       end
 
-      # The Proc the Dispatcher passes as +&block+, binding #yield so a
-      # Service method's +yield+ / +block.call+ drives the round-trip.
       def to_proc
         method(:yield).to_proc
       end
 
-      # Mark this Yielder dead. Called by the Dispatcher's +ensure+ block
-      # when the originating dispatch frame returns; any later #yield
-      # call then raises +LocalJumpError+.
-      def invalidate!
+      def invalidate
         @active = false
       end
 
       private
 
-      # Encode what the Service is yielding. Arguments outside the wire
-      # type set, or nesting past the wire's bound as one list, fail here,
-      # before the guest is re-entered, and are restated so the Service
-      # reads a refusal of its own argument rather than a codec class it
-      # never named.
+      # Restated so the Service reads a refusal of its own argument rather
+      # than a codec class it never named.
       def encode_args(args)
         Kobako::Codec::Nesting.assert_within_bound!(args)
         Kobako::Codec::Encoder.encode(args)
@@ -106,33 +48,17 @@ module Kobako
         raise YieldValueError, "Service yielded a value the block cannot receive: #{e.message}"
       end
 
-      # Hold onto the BlockError being raised so #fault_text can recognise
-      # it if it comes back unrescued, and return it so the raise site reads
-      # as one statement. Only the newest is kept: a Service that rescued
-      # an earlier one and yielded again has already handled it.
-      def remember(error)
-        @raised = error
-      end
-
-      # Decode a value-carrying arm's payload, answering the value and
-      # whether the decode carried a Capability Handle. The tracking
-      # bracket opens only around this decode: the guest re-entry may run
-      # nested dispatches whose own brackets would otherwise pollute the
-      # signal.
+      # The tracking bracket opens only around this decode: the guest
+      # re-entry may run nested dispatches whose own brackets would
+      # otherwise pollute the signal.
       def decode_body(body)
         Kobako::Codec.track_handles { Kobako::Codec::Decoder.decode(body) }
       end
 
-      # Restore any Capability Handle in a block's ok value to its host
-      # 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. A response
-      # whose decode carried no Handle resolves to itself, so the walk is
-      # skipped entirely.
       def restore(value, carried_handle)
         return value unless carried_handle
 
-        Kobako::Codec::HandleWalk.deep_restore(value, @handler)
+        Kobako::Codec::HandleWalk.deep_restore(value, @handles)
       end
     end
   end

data/lib/kobako/transport.rb

@@ -2,6 +2,7 @@
 
 require_relative "transport/call"
 require_relative "transport/run"
+require_relative "transport/block_failure"
 require_relative "transport/yielder"
 require_relative "transport/error"
 require_relative "transport/exposure"
@@ -9,20 +10,8 @@ require_relative "transport/reflection"
 require_relative "transport/dispatcher"
 
 module Kobako
-  # Kobako::Transport — host↔guest message transport namespace. Houses the
-  # host side of one Call/Reply exchange: the call value objects +Call+
-  # (guest→host, as the native side decoded it) and +Run+ (host→guest), the
-  # +Dispatcher+ that answers a routed Call, the +Yielder+ that re-enters
-  # the guest for a block, the +Reflection+ floor a dispatch must clear, the
-  # +Exposure+ each reference authorizes a call against, and +Error+ for a
-  # wire violation the host detects. Each invocation's
-  # +Context+ composes them into the dispatch +Proc+ it passes +Runtime+ for
-  # that run.
-  #
-  # "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].
-  module Transport
+  # The host side of the guest↔host exchange. Only Transport::Error is
+  # public; the rest serves one invocation's dispatch.
+  module Transport # :nodoc:
   end
 end

data/lib/kobako/unresolved.rb

@@ -1,17 +1,10 @@
 # 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.
+  # Stands for the object of a fillable Service, one declared with
+  # Sandbox#bind and no object. Context#bind supplies the object for an
+  # invocation; a call to one left unfilled fails as a ServiceError. Passing
+  # it to Sandbox#bind declares a fillable explicitly.
   module Unresolved
   end
 end

data/lib/kobako/usage.rb

@@ -12,14 +12,10 @@ module Kobako
   #     cap, even when the cap was hit.
   #
   # Filled on every outcome, traps included, so a Host App that rescues a
-  # trap can read from the error's +#execution+ how much of the budget the
+  # trap reads from the error's +execution+ how much of the budget the
   # invocation used.
-  #
-  # Built on the +class X < Data.define(...)+ subclass form (the
-  # Steep-friendly shape — see +.rubocop.yml+ for the rationale).
   class Usage < Data.define(:wall_time, :memory_peak)
-    # Pre-run sentinel. A fresh +Kobako::Context+ holds it until its guest
-    # runs, so an Execution's +#usage+ is never +nil+.
+    # The usage of a run that has not started: no time, no memory.
     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.27.0"
+  VERSION = "0.29.0"
 end

data/lib/kobako.rb

@@ -9,6 +9,7 @@ rescue LoadError
   require "kobako/kobako"
 end
 
+require_relative "kobako/filesystem"
 require_relative "kobako/errors"
 require_relative "kobako/unresolved"
 require_relative "kobako/extension"

data/sig/kobako/catalog/extensions.rbs

@@ -5,7 +5,7 @@ module Kobako
 
       def install: (untyped extension, snippets: Kobako::Catalog::Snippets, services: Kobako::Catalog::Services) -> self
 
-      def seal!: () -> self
+      def assert_dependencies!: () -> self
 
       def resolve: () -> Hash[String, untyped]
 
@@ -17,7 +17,7 @@ module Kobako
 
       def validate!: (untyped extension) -> void
 
-      def assert_dependencies!: () -> void
+      def unmet_dependency: () -> [untyped, untyped]?
 
       def symbolize: (untyped name) -> untyped
     end

data/sig/kobako/catalog/flags.rbs

@@ -0,0 +1,13 @@
+module Kobako
+  module Catalog
+    class Flags
+      type tuple = [String, String, bool]
+
+      def initialize: () -> void
+
+      def entries: () -> Array[tuple]
+
+      def register: (Symbol | String name, String value, advisory: bool) -> nil
+    end
+  end
+end

data/sig/kobako/catalog/grants.rbs

@@ -0,0 +1,13 @@
+module Kobako
+  module Catalog
+    class Grants
+      def initialize: () -> void
+
+      def register: (Mount grant) -> nil
+
+      def include?: (Mount grant) -> bool
+
+      def entries: (?Hash[String, Mount] overrides) -> Array[Mount::tuple]
+    end
+  end
+end