kobako 0.19.0 → 0.21.0

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,42 +1,36 @@
 # frozen_string_literal: true
 
-require_relative "handles"
-require_relative "../codec"
 require_relative "../errors"
 
 module Kobako
   module Catalog
     # Kobako::Catalog::Services — per-Sandbox registry of Service
     # bindings keyed by their constant-path name. Holds the flat
-    # path→object table and the preamble emitted on Frame 1.
+    # path→object table and the declared path set every invocation
+    # announces on Frame 1.
     #
     # Public API:
     #
     #   services = Kobako::Catalog::Services.new
     #   services.bind("MyService::KV", kv_object)  # => services (chainable)
-    #   services.encode                            # => msgpack bytes for Frame 1
+    #   services.paths                             # => ["MyService::KV"]
     #   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
 
       # Bind +object+ as the Service reachable at +path+ — a +Symbol+ or
@@ -56,6 +50,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,38 +65,16 @@ 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
-      # like every other host-side wire encode; the preamble carries only
-      # 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.
-      def encode
-        return @encoded if @encoded
-
-        bytes = Codec::Encoder.encode(@bindings.keys).freeze
-        @encoded = bytes if @sealed
-        bytes
+      # The bound constant paths in bind order — +["MyService::KV",
+      # "File"]+ — which +Runtime#eval+ / +#run+ frame into the Frame 1
+      # preamble. The registry holds the bindings; the wire layout is the
+      # native side's.
+      def paths
+        @bindings.keys
       end
 
-      # Mark the registry as sealed. Called by +Sandbox+ on the first
+      # Mark the registry as sealed so registration can never alter the
+      # declared path set afterwards. Called by +Sandbox+ on the first
       # invocation; afterwards #bind raises ArgumentError. Idempotent;
       # returns +self+.
       def seal!

data/lib/kobako/catalog/snippets.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../codec"
 require_relative "../snippet"
 
 module Kobako
@@ -28,30 +27,16 @@ module Kobako
 
       def initialize
         @entries = [] # : Array[Kobako::Snippet::Source | Kobako::Snippet::Binary]
-        @encoded = nil # : String?
       end
 
-      # Serialize the registered snippets to wire bytes. Each entry
-      # contributes a msgpack map shape; the collection rides as a single
-      # msgpack array. An empty registry serializes to an empty array, never
-      # absent. The wire codec is an implementation detail — callers
-      # receive a binary +String+ that the +Kobako::Runtime+ layer ships
-      # through the invocation channel. The entry value objects stay pure
-      # carriers — this collection-tier method reads their attributes
-      # 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.
-      def encode
-        return @encoded if @encoded
-
-        @encoded = Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) }).freeze
+      # The registered snippets in insertion order, each projected as the
+      # +[kind, name, body]+ triple +Runtime#eval+ / +#run+ frame into
+      # Frame 3 — +kind+ names the form as a Symbol, +name+ is +nil+ for
+      # the bytecode form. The entry value objects stay pure carriers, so
+      # this collection-tier method reads their attributes externally
+      # rather than asking each entry to project itself.
+      def entries
+        @entries.map { |entry| entry_tuple(entry) }
       end
 
       # Register one preloaded snippet in either of two forms.
@@ -73,7 +58,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
 
@@ -123,17 +107,16 @@ module Kobako
         nil
       end
 
-      # Build the msgpack-ready Hash for one entry. Source entries
-      # contribute their host-side +name+; Binary entries omit it
-      # because the canonical name lives in the bytecode's embedded
-      # +debug_info+ and is read by the guest at load time
-      # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
-      def entry_payload(entry)
+      # Project one entry as its +[kind, name, body]+ triple. Source
+      # entries contribute their host-side +name+; Binary entries carry
+      # +nil+ because the canonical name lives in the bytecode's embedded
+      # +debug_info+ and is read by the guest at load time.
+      def entry_tuple(entry)
         case entry
         when Snippet::Source
-          { "name" => entry.name.to_s, "kind" => Snippet::Source::KIND, "body" => entry.body }
-        when Snippet::Binary
-          { "kind" => Snippet::Binary::KIND, "body" => entry.body }
+          [Snippet::Source::KIND, entry.name.to_s, entry.body]
+        else
+          [Snippet::Binary::KIND, nil, entry.body]
         end
       end
 

data/lib/kobako/codec/decoder.rb

@@ -9,10 +9,10 @@ require_relative "utils"
 module Kobako
   module Codec
     # Module-level entry point for the host side of the kobako wire
-    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type Mapping).
+    # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Type Mapping).
     #
     # Translates msgpack gem exceptions into the kobako error taxonomy
-    # (Truncated, InvalidType, InvalidEncoding, UnsupportedType) so
+    # (TruncatedInputError, InvalidTypeError, InvalidEncodingError, UnsupportedTypeError) so
     # callers can pattern-match on the SPEC's wire-violation categories
     # without leaking the gem's internal exception classes.
     #
@@ -21,14 +21,14 @@ module Kobako
     # because callers always decode exactly one wire value at a time.
     module Decoder
       # Decode +bytes+ into one Ruby value and validate transitively
-      # against the SPEC type mapping. Raises Truncated, InvalidType,
-      # or InvalidEncoding on wire violations.
+      # against the SPEC type mapping. Raises TruncatedInputError, InvalidTypeError,
+      # or InvalidEncodingError on wire violations.
       #
       # When a block is given, the decoded value is yielded and the block's
       # result is returned — wire Value Objects use this to build themselves
       # from the decoded payload. The block runs inside this method's
       # rescue, so a Value Object's +ArgumentError+ invariant failure
-      # surfaces as InvalidType without a separate Utils.with_boundary
+      # surfaces as InvalidTypeError without a separate Utils.with_boundary
       # wrapper at the call site.
       def self.decode(bytes)
         value = FACTORY.load(bytes.b)
@@ -37,26 +37,23 @@ module Kobako
       # msgpack gem raises the format/type errors below; +ArgumentError+
       # comes from our ext-type validators (Handle id range, Exception type
       # whitelist) and from a yielded block's Value Object invariants — both
-      # are wire violations, so both map to InvalidType.
+      # are wire violations, so both map to InvalidTypeError.
       rescue ::MessagePack::UnknownExtTypeError, ::MessagePack::MalformedFormatError,
              ::MessagePack::StackError, ::ArgumentError => e
-        raise InvalidType, e.message
+        raise InvalidTypeError, e.message
       # +UnpackError+ is the gem's umbrella class for short-read /
       # incomplete-buffer faults; +EOFError+ covers underflow at the
       # buffer edge.
       rescue ::MessagePack::UnpackError, ::EOFError => e
-        raise Truncated, e.message
+        raise TruncatedInputError, e.message
       end
 
       # SPEC pins +str+ family payloads to UTF-8
-      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § str/bin
+      # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § str/bin
       # Encoding Rules). The msgpack gem returns UTF-8-tagged Strings for
       # str family but does not validate the bytes; +bin+ family decodes
       # to ASCII-8BIT. Walk the tree once and reject invalid UTF-8 in any
-      # str-typed leaf via Utils.assert_utf8!. Kobako::Fault
-      # payloads are validated transitively: +ExtTypes#unpack_fault+
-      # feeds the inner ext-0x02 bytes back through this Decoder, so their
-      # +str+ fields are already covered by the time control returns here.
+      # str-typed leaf via Utils.assert_utf8!.
       class << self
         private
 

data/lib/kobako/codec/encoder.rb

@@ -8,13 +8,13 @@ require_relative "ext_types"
 module Kobako
   module Codec
     # Module-level entry point for the host side of the kobako wire
-    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type Mapping).
+    # ({docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Type Mapping).
     #
     # The codec backbone is the official +msgpack+ gem: integers, floats,
     # strings, arrays, and maps go through the gem's narrowest-encoding
-    # logic; the three kobako-specific ext types (0x00 Symbol, 0x01
-    # Capability Handle, 0x02 Exception envelope) are registered by
-    # ExtTypes on the process-wide factory.
+    # logic; the two kobako-specific ext types (0x00 Symbol, 0x01
+    # Capability Handle) are registered by ExtTypes on the process-wide
+    # factory.
     #
     # Public API is a single function — +.encode+. The codec is stateless;
     # there is no buffer accumulator and no streaming write API. Callers
@@ -22,8 +22,8 @@ module Kobako
     # themselves.
     module Encoder
       # Encode +value+ to wire bytes (binary-encoded String).
-      # SPEC's 12-entry type mapping is a closed set: a value outside it is
-      # rejected as +UnsupportedType+ by the factory's +BasicObject+ guard
+      # SPEC's 11-entry type mapping is a closed set: a value outside it is
+      # rejected as +UnsupportedTypeError+ by the factory's +BasicObject+ guard
       # (ExtTypes#register_unrepresentable), which raises before the msgpack
       # gem can route the value through +to_msgpack+ — so a permissive
       # +method_missing+ object cannot answer that probe and mis-encode. The
@@ -33,7 +33,7 @@ module Kobako
       def self.encode(value)
         FACTORY.dump(value)
       rescue ::RangeError, ::NoMethodError => e
-        raise UnsupportedType, e.message
+        raise UnsupportedTypeError, e.message
       end
     end
   end

data/lib/kobako/codec/error.rb

@@ -5,7 +5,7 @@ module Kobako
     # Base class for all wire-codec faults raised by the pure-Ruby host codec.
     #
     # The wire codec implements the binary contract pinned in
-    # {docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type Mapping.
+    # {docs/wire/payload-msgpack.md}[link:../../../docs/wire/payload-msgpack.md] § Type Mapping.
     # Every wire violation surfaces as a
     # subclass of Error so callers can pattern-match on the specific
     # fault while still rescuing all codec faults via this base class.
@@ -15,20 +15,20 @@ module Kobako
     class Error < StandardError; end
 
     # Input ended before the type prefix or payload was fully consumed.
-    class Truncated < Error; end
+    class TruncatedInputError < Error; end
 
-    # The type byte at the current position is not in the 12-entry kobako
+    # The type byte at the current position is not in the 11-entry kobako
     # type mapping (e.g. an unknown ext code, or a reserved msgpack tag).
-    class InvalidType < Error; end
+    class InvalidTypeError < Error; end
 
     # A msgpack +str+ payload was not valid UTF-8, or an ext 0x00 Symbol
     # payload was not valid UTF-8 — both are wire violations per SPEC.
-    class InvalidEncoding < Error; end
+    class InvalidEncodingError < Error; end
 
     # The encoder was handed a Ruby object whose type has no wire
     # representation (e.g. Range, Time). Higher layers may catch this
     # and re-route the value through Handle allocation, but at the
     # codec level it is a hard error.
-    class UnsupportedType < Error; end
+    class UnsupportedTypeError < Error; end
   end
 end