kobako 0.3.0 → 0.5.0

data/lib/kobako/transport/dispatcher.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require_relative "../codec"
+require_relative "request"
+require_relative "response"
+require_relative "yield"
+require_relative "yielder"
+
+module Kobako
+  # See lib/kobako/transport.rb for the umbrella module doc; this file
+  # owns the pure-function dispatcher that decodes guest-initiated
+  # Requests and produces encoded Responses.
+  module Transport
+    # Pure-function dispatcher for guest-initiated transport calls.
+    # Decodes a msgpack-encoded Request envelope, resolves the target
+    # object through the Catalog::Namespaces (path lookup) or
+    # Catalog::Handles (Handle lookup), invokes the method, and returns
+    # a msgpack-encoded Response envelope.
+    #
+    # The module is stateless — all mutable state is threaded through
+    # arguments so Dispatcher has no instance variables and no side
+    # effects beyond mutating the Catalog::Handles via +alloc+ when a
+    # non-wire-representable return value must be wrapped
+    # ({docs/behavior.md B-14}[link:../../../docs/behavior.md]).
+    #
+    # Entry point:
+    #
+    #   Kobako::Transport::Dispatcher.dispatch(request_bytes, namespaces, handler, yield_to_guest)
+    #   # => msgpack-encoded Response bytes (never raises)
+    module Dispatcher
+      # Throw tag for the {Yielder}'s break unwind back to the
+      # dispatcher's +catch+ frame (B-25). +private_constant+ is a
+      # convention boundary — not a defence.
+      BREAK_THROW = :__kobako_break__
+      private_constant :BREAK_THROW
+
+      module_function
+
+      # Internal sentinel raised when target resolution fails. Mapped to
+      # Response.error with type="undefined". Contained at the wire boundary —
+      # not part of the public Kobako error taxonomy
+      # ({docs/behavior.md E-12}[link:../../../docs/behavior.md]).
+      class UndefinedTargetError < StandardError; end
+
+      # Dispatch a single transport request and return the encoded
+      # Response bytes ({docs/behavior.md B-12}[link:../../../docs/behavior.md]).
+      # Invoked from the +Runtime#on_dispatch+ Proc that
+      # +Kobako::Sandbox#initialize+ installs on the ext side; +namespaces+,
+      # +handler+, and +yield_to_guest+ are captured in that Proc's
+      # closure so the Dispatcher stays stateless and the registry doesn't
+      # need to publish accessors for the Sandbox-owned +Catalog::Handles+
+      # or +Runtime+. +yield_to_guest+ is a +String → String+ callable
+      # (typically +Runtime#yield_to_active_invocation+ bound as a lambda)
+      # used only when the Request carries +block_given: true+. Always
+      # returns a binary String — every failure path is reified as a
+      # Response.error envelope so the guest sees a transport error rather
+      # than a wasm trap.
+      def dispatch(request_bytes, namespaces, handler, yield_to_guest)
+        request = Kobako::Transport::Request.decode(request_bytes)
+        target = resolve_target(request.target, namespaces, handler)
+        args, kwargs = resolve_call_args(request, handler)
+        yielder = Yielder.new(yield_to_guest, BREAK_THROW) if request.block_given
+        value = catch(BREAK_THROW) { invoke(target, request.method_name, args, kwargs, yielder) }
+        encode_ok(value, handler)
+      rescue StandardError => e
+        encode_caught_error(e)
+      ensure
+        yielder&.invalidate!
+      end
+
+      # Resolve positional and keyword arguments off +request+ in one
+      # step. Both pass through {#resolve_arg} so Capability Handles
+      # round-trip back to the host-side Ruby object before the call
+      # reaches +public_send+.
+      def resolve_call_args(request, handler)
+        args = request.args.map { |v| resolve_arg(v, handler) }
+        kwargs = request.kwargs.transform_values { |v| resolve_arg(v, handler) }
+        [args, kwargs]
+      end
+
+      # Map an error caught at the dispatch boundary to a +Response.error+
+      # envelope. +error+ is the +StandardError+ caught by {#dispatch}'s
+      # rescue. Returns a msgpack-encoded Response envelope (binary). Three
+      # error buckets ({docs/behavior.md B-12}[link:../../../docs/behavior.md]):
+      # +Kobako::Codec::Error+ → type="runtime" (malformed request);
+      # +UndefinedTargetError+ → type="undefined" (E-13); +ArgumentError+ →
+      # type="argument" (B-12 arity mismatch); everything else →
+      # type="runtime".
+      def encode_caught_error(error)
+        case error
+        when Kobako::Codec::Error then encode_error("runtime",
+                                                    "Sandbox received a malformed request: #{error.message}")
+        when UndefinedTargetError then encode_error("undefined", error.message)
+        when ArgumentError        then encode_error("argument", error.message)
+        else                           encode_error("runtime", "#{error.class}: #{error.message}")
+        end
+      end
+
+      # Dispatch +method+ on +target+. +kwargs+ is already Symbol-keyed
+      # (the +Request+ invariant pins it). The empty-kwargs branch omits
+      # the +**+ splat so Ruby 3.x's strict kwargs separation does not
+      # reject calls to no-kwarg methods when the wire carries the
+      # uniform empty-map shape.
+      #
+      # +yielder+ is the host-side {Yielder} materialised when the guest
+      # call site supplied a block ({docs/behavior.md
+      # B-23}[link:../../../docs/behavior.md]); its {Yielder#to_proc}
+      # rides the +&block+ slot. +&nil+ is a no-op block argument in Ruby,
+      # so the same call site handles both cases without an explicit
+      # conditional.
+      def invoke(target, method, args, kwargs, yielder = nil)
+        block = yielder&.to_proc
+        if kwargs.empty?
+          target.public_send(method.to_sym, *args, &block)
+        else
+          target.public_send(method.to_sym, *args, **kwargs, &block)
+        end
+      end
+
+      # {docs/behavior.md B-16}[link:../../../docs/behavior.md] — An Kobako::Handle arriving as a positional or keyword
+      # argument identifies a host-side object previously allocated by a prior
+      # transport call's Handle wrap (B-14). Resolve it back to the Ruby object before
+      # the dispatch reaches +public_send+.
+      def resolve_arg(value, handler)
+        case value
+        when Kobako::Handle
+          require_live_object!(value.id, handler)
+        else
+          value
+        end
+      end
+
+      # Resolve a Request target to the Ruby object the registry (or
+      # Catalog::Handles) holds. String targets go through the registry;
+      # Handle targets (ext 0x01) go through the Catalog::Handles.
+      #
+      # Target type is already validated by +Transport::Request.decode+
+      # before this method is reached, so no else-branch is needed here —
+      # the wire layer is the system boundary that enforces the invariant.
+      def resolve_target(target, namespaces, handler)
+        case target
+        when String
+          resolve_path(target, namespaces)
+        when Kobako::Handle
+          resolve_handle(target, handler)
+        end
+      end
+
+      def resolve_path(path, namespaces)
+        namespaces.lookup(path)
+      rescue KeyError => e
+        raise UndefinedTargetError, e.message
+      end
+
+      def resolve_handle(handle, handler)
+        require_live_object!(handle.id, handler)
+      end
+
+      # Resolve +id+ through the Catalog::Handles. An unknown id (E-13)
+      # surfaces as UndefinedTargetError.
+      def require_live_object!(id, handler)
+        handler.fetch(id)
+      rescue Kobako::SandboxError => e
+        raise UndefinedTargetError, e.message
+      end
+
+      # Encode +value+ as a +Response.ok+ envelope. When the value is not
+      # wire-representable per {docs/behavior.md B-13}[link:../../../docs/behavior.md]'s type
+      # mapping, the +UnsupportedType+ rescue routes it through the
+      # Catalog::Handles via {#wrap_as_handle} and re-encodes with the Capability
+      # Handle in place ({docs/behavior.md B-14}[link:../../../docs/behavior.md]). The happy
+      # path encodes exactly once.
+      def encode_ok(value, handler)
+        response = Kobako::Transport::Response.ok(value)
+        response.encode
+      rescue Kobako::Codec::UnsupportedType
+        encode_ok(wrap_as_handle(value, handler), handler)
+      end
+
+      # Allocate +value+ in the Sandbox's Catalog::Handles and return a +Handle+
+      # that the wire codec can carry ({docs/behavior.md B-14}[link:../../../docs/behavior.md]).
+      # Used as the fallback path of {#encode_ok} when +value+ has no wire
+      # representation.
+      def wrap_as_handle(value, handler)
+        handler.alloc(value)
+      end
+
+      def encode_error(type, message)
+        fault = Kobako::Fault.new(type: type, message: message)
+        response = Kobako::Transport::Response.error(fault)
+        response.encode
+      end
+    end
+  end
+end

data/lib/kobako/transport/error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Kobako
+  module Transport
+    # +Kobako::SandboxError+ subclass raised when the host detects a
+    # structural violation of the wire contract while decoding bytes
+    # produced by the guest (a malformed Outcome envelope, a result body
+    # that fails msgpack decode, a Panic envelope missing required
+    # fields). Distinct from a Wasm trap (engine signalled the guest
+    # runtime is unrecoverable) and from a normal sandbox-layer failure
+    # (the script raised but the protocol was respected): a
+    # +Transport::Error+ always indicates the guest runtime is corrupted —
+    # the only safe recovery is to discard the Sandbox and start a new
+    # invocation.
+    #
+    # Inherits from +Kobako::SandboxError+ so a single
+    # +rescue Kobako::SandboxError+ still catches it; callers that want
+    # to distinguish wire-violation paths from script failures can
+    # +rescue Kobako::Transport::Error+ directly.
+    class Error < Kobako::SandboxError; end
+  end
+end

data/lib/kobako/transport/request.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../handle"
+require_relative "../codec"
+
+module Kobako
+  # See lib/kobako/transport.rb for the umbrella module doc; this file
+  # owns the Request value object and its +#encode+ / +.decode+ codec,
+  # plus the +STATUS_OK+ / +STATUS_ERROR+ constants shared with Response.
+  module Transport
+    # ---------------- Response status bytes (docs/wire-contract.md § Response Shape) ---
+
+    # Response variant marker for the success branch.
+    STATUS_OK    = 0
+    # Response variant marker for the fault branch.
+    STATUS_ERROR = 1
+
+    # Value object for a single guest-initiated Transport Request
+    # ({docs/wire-codec.md Envelope Encoding → Request}[link:../../../docs/wire-codec.md]).
+    #
+    # 5-element msgpack array:
+    # +[target, method_name, args, kwargs, block_given]+. +target+ is
+    # either a +String+ (+"Namespace::Member"+) or a {Handle}. SPEC pins
+    # +kwargs+ map keys to ext 0x00 Symbol; enforced at construction so
+    # the Value Object is the single source of truth. +block_given+ is a
+    # Boolean signalling whether the guest call site supplied a block
+    # (B-23); the block body itself never crosses the wire.
+    #
+    # Built on the +class X < Data.define(...)+ subclass form so the
+    # class body is fully Steep-visible; see +lib/kobako/outcome/panic.rb+
+    # for the rationale.
+    class Request < Data.define(:target, :method_name, :args, :kwargs, :block_given)
+      def initialize(target:, method_name:, args: [], kwargs: {}, block_given: false)
+        unless target.is_a?(String) || target.is_a?(Kobako::Handle)
+          raise ArgumentError, "Request target must be String or Kobako::Handle, got #{target.class}"
+        end
+        raise ArgumentError, "Request method_name must be String" unless method_name.is_a?(String)
+        raise ArgumentError, "Request args must be Array"         unless args.is_a?(Array)
+        unless block_given.is_a?(TrueClass) || block_given.is_a?(FalseClass)
+          raise ArgumentError, "Request block_given must be Boolean, got #{block_given.class}"
+        end
+
+        validate_kwargs!(kwargs)
+        super
+      end
+
+      # Encode this Request to msgpack bytes. The Value Object's own
+      # invariants are the contract; this method does not re-check the shape.
+      def encode
+        Codec::Encoder.encode([target, method_name, args, kwargs, block_given])
+      end
+
+      # Decode +bytes+ into a {Request}. Raises +Codec::InvalidType+ when the
+      # envelope is not the expected 5-element msgpack array, or when the
+      # Value Object's construction invariants reject the decoded fields.
+      def self.decode(bytes)
+        Codec::Decoder.decode(bytes) do |arr|
+          unless arr.is_a?(Array) && arr.length == 5
+            raise Codec::InvalidType, "Request envelope is malformed (expected a 5-element array)"
+          end
+
+          target, method_name, args, kwargs, block_given = arr
+          new(target: target, method_name: method_name, args: args, kwargs: kwargs, block_given: block_given)
+        end
+      end
+
+      private
+
+      def validate_kwargs!(kwargs)
+        raise ArgumentError, "Request kwargs must be Hash" unless kwargs.is_a?(Hash)
+
+        kwargs.each_key do |k|
+          raise ArgumentError, "Request kwargs keys must be Symbol, got #{k.class}" unless k.is_a?(Symbol)
+        end
+      end
+    end
+  end
+end

data/lib/kobako/transport/response.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../codec"
+require_relative "../fault"
+require_relative "request"
+
+module Kobako
+  # See lib/kobako/transport.rb for the umbrella module doc; this file
+  # owns the Response value object and its +#encode+ / +.decode+ codec.
+  module Transport
+    # Value object for a single host-side Transport Response
+    # ({docs/wire-codec.md Envelope Encoding → Response}[link:../../../docs/wire-codec.md]).
+    #
+    # 2-element msgpack array: +[status, value-or-fault]+. +status+ is 0
+    # (success) or 1 (fault). For success the second element is the return
+    # value; for fault it is a {Fault} (ext 0x02 envelope).
+    #
+    # Built on the +class X < Data.define(...)+ subclass form so the
+    # class body is fully Steep-visible; see +lib/kobako/outcome/panic.rb+
+    # for the rationale.
+    class Response < Data.define(:status, :payload)
+      def self.ok(value)
+        new(status: STATUS_OK, payload: value)
+      end
+
+      def self.error(fault)
+        unless fault.is_a?(Kobako::Fault)
+          raise ArgumentError, "Response.error requires Kobako::Fault, got #{fault.class}"
+        end
+
+        new(status: STATUS_ERROR, payload: fault)
+      end
+
+      # Decode +bytes+ into a {Response}. Raises +Codec::InvalidType+ when the
+      # envelope is not the expected 2-element msgpack array, or when the
+      # Value Object's construction invariants reject the decoded fields.
+      def self.decode(bytes)
+        Codec::Decoder.decode(bytes) do |arr|
+          unless arr.is_a?(Array) && arr.length == 2
+            raise Codec::InvalidType, "Response envelope is malformed (expected a 2-element array)"
+          end
+
+          status, payload = arr
+          new(status: status, payload: payload)
+        end
+      end
+
+      def initialize(status:, payload:)
+        unless [STATUS_OK, STATUS_ERROR].include?(status)
+          raise ArgumentError, "Response status must be 0 (ok) or 1 (error), got #{status.inspect}"
+        end
+        if status == STATUS_ERROR && !payload.is_a?(Kobako::Fault)
+          raise ArgumentError, "Response with error status must carry a Kobako::Fault payload"
+        end
+
+        super
+      end
+
+      def ok?    = status == STATUS_OK
+      def error? = status == STATUS_ERROR
+
+      # Encode this Response to msgpack bytes as the 2-element
+      # +[status, payload]+ array.
+      def encode
+        Codec::Encoder.encode([status, payload])
+      end
+    end
+  end
+end

data/lib/kobako/transport/run.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "../handle"
+require_relative "../codec"
+
+module Kobako
+  # See lib/kobako/transport.rb for the umbrella module doc; this file
+  # owns the +Run+ envelope value object — the host→guest request shape
+  # consumed by +__kobako_run+.
+  module Transport
+    # Host-side value object for a single +Sandbox#run+ invocation
+    # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md];
+    # {docs/behavior.md B-31}[link:../../../docs/behavior.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 (E-24 / E-25 / E-29 / E-30) is enforced at
+    # construction so the Value Object is the single source of truth —
+    # anything that passes +Run.new+ is safe to encode and ship to
+    # the guest.
+    #
+    # Run is the host→guest entrypoint dispatch envelope (the +#run+
+    # request shape), the symmetric counterpart to the guest→host
+    # +Request+ envelope. +#encode+ takes the Sandbox's
+    # +Catalog::Handles+ and routes any non-wire-representable +args+ /
+    # +kwargs+ leaf through it as a +Kobako::Handle+
+    # ({docs/behavior.md B-34}[link:../../../docs/behavior.md]) — the
+    # symmetric counterpart of the guest→host wrap path in the
+    # dispatcher (B-14). A +Kobako::Handle+ that arrives **already
+    # constructed** in the caller's +args+ / +kwargs+ is rejected at
+    # construction (E-29): legitimate Handles only enter Host App code
+    # through error fields, so a Handle reaching the call site is by
+    # definition smuggled in. The +#encode+ output is the "Run envelope"
+    # that ships through the +__kobako_run+ command buffer.
+    #
+    # Built on the +class X < Data.define(...)+ subclass form (the
+    # Steep-friendly shape — see +lib/kobako/outcome/panic.rb+).
+    class Run < Data.define(:entrypoint, :args, :kwargs)
+      # Ruby constant-name pattern enforced on the +entrypoint+ Symbol
+      # ({docs/behavior.md E-25}[link:../../../docs/behavior.md]). 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/
+
+      def initialize(entrypoint:, args: [], kwargs: {})
+        entrypoint = normalize_entrypoint(entrypoint)
+        args = validate_args!(args)
+        kwargs = validate_kwargs!(kwargs)
+        super
+      end
+
+      # Encode this Run to the msgpack bytes the guest's +__kobako_run+
+      # entry point consumes as its command-buffer payload
+      # ({docs/wire-codec.md Invocation channels}[link:../../../docs/wire-codec.md]).
+      # Walks +args+ / +kwargs+ through {Codec::Utils.deep_wrap} so any
+      # non-wire-representable leaf is allocated into +handler+ and
+      # replaced with a +Kobako::Handle+
+      # ({docs/behavior.md B-34}[link:../../../docs/behavior.md]); the
+      # +handler+ argument is the Sandbox's table, sharing the same
+      # allocator the guest→host return path (B-14) uses.
+      #
+      # Layout: msgpack map with string keys +"entrypoint"+ (Symbol via
+      # ext 0x00), +"args"+ (Array), +"kwargs"+ (Map with Symbol keys);
+      # any wrapped leaf rides as ext 0x01 in its original position
+      # (docs/wire-codec.md § ext 0x01 position rules).
+      def encode(handler)
+        Codec::Encoder.encode(
+          "entrypoint" => entrypoint,
+          "args" => Codec::Utils.deep_wrap(args, handler),
+          "kwargs" => Codec::Utils.deep_wrap(kwargs, handler)
+        )
+      end
+
+      private
+
+      # E-24: 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). E-25: after +.to_s+
+      # the value must match NAME_PATTERN (ArgumentError), rejecting
+      # +::+-segmented names and any non-constant form.
+      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)
+          raise ArgumentError,
+                "entrypoint must match #{NAME_PATTERN.inspect} (got #{target.inspect})"
+        end
+
+        target_str.to_sym
+      end
+
+      # E-29: +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 +#encode+ (B-34) — 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)
+
+        args
+      end
+
+      # E-30 covers the non-Symbol kwargs-key case; E-29 also rejects 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.
+      def validate_kwargs!(kwargs)
+        raise ArgumentError, "keyword arguments must be a Hash" unless kwargs.is_a?(Hash)
+
+        bad_keys = kwargs.each_key.grep_v(Symbol)
+        unless bad_keys.empty?
+          raise ArgumentError,
+                "keyword argument keys must be Symbols (got #{bad_keys.inspect})"
+        end
+        raise ArgumentError, forged_handle_message("keyword argument values") if kwargs.each_value.any?(Kobako::Handle)
+
+        kwargs
+      end
+
+      # Single source of truth for the E-29 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 SPEC anchor identifiers (B-xx / E-xx live in
+      # source comments, not user-visible errors) 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"
+      end
+    end
+  end
+end

data/lib/kobako/transport/yield.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../codec"
+
+module Kobako
+  # See lib/kobako/transport.rb for the umbrella module doc; this file
+  # owns the +Yield+ envelope value object plus its +#encode+ / +.decode+
+  # codec for the +__kobako_yield_to_block+ wire form.
+  module Transport
+    # First byte of the YieldResponse for the success branch — body is
+    # the block's return value encoded as a single msgpack value.
+    TAG_OK = 0x01
+    # First byte for `break val` — body is the break value.
+    TAG_BREAK = 0x02
+    # Reserved for future `return val` support; both sides reject this
+    # tag as a wire violation (YieldResponse envelope contract).
+    TAG_RESERVED = 0x03
+    # First byte for an error / fault outcome — body is a
+    # +{"class", "message", "backtrace"}+ Hash.
+    TAG_ERROR = 0x04
+
+    # Tags both sides currently accept on the wire.
+    LIVE_TAGS = [TAG_OK, TAG_BREAK, TAG_ERROR].freeze
+
+    # Value object for a single YieldResponse envelope
+    # ({docs/wire-codec.md YieldResponse Envelope}[link:../../../docs/wire-codec.md]).
+    #
+    # The wire form is a one-byte tag followed by an msgpack payload.
+    # The three live tags are +0x01+ (ok), +0x02+ (break), and +0x04+
+    # (error); +0x03+ is reserved and rejected by both sides.
+    #
+    # +value+ carries whatever the wire payload decoded to — a plain
+    # Ruby value for the +ok+ / +break+ tags, and a +{"class",
+    # "message", "backtrace"}+ Hash for the +error+ tag. No further
+    # shape constraint is enforced here; the host-side dispatcher
+    # decides how to translate each variant into Ruby control flow.
+    #
+    # Lives alongside the other envelope value objects (+Request+,
+    # +Response+) since it is the guest-to-host shape used
+    # mid-dispatch-frame to answer a +__kobako_yield_to_block+ re-entry.
+    class Yield < Data.define(:tag, :value)
+      def initialize(tag:, value:)
+        unless Kobako::Transport::LIVE_TAGS.include?(tag)
+          raise ArgumentError,
+                "Yield tag must be one of #{Kobako::Transport::LIVE_TAGS.inspect}, got #{tag.inspect}"
+        end
+
+        super
+      end
+
+      def ok?    = tag == Kobako::Transport::TAG_OK
+      def break? = tag == Kobako::Transport::TAG_BREAK
+      def error? = tag == Kobako::Transport::TAG_ERROR
+
+      # Encode this Yield to YieldResponse bytes: one tag byte followed
+      # by an msgpack-encoded +value+.
+      def encode
+        [tag].pack("C") + Codec::Encoder.encode(value)
+      end
+
+      # Decode +bytes+ into a {Yield}. Rejects empty input, the reserved
+      # tag 0x03, and any tag outside +LIVE_TAGS+ by raising
+      # +Kobako::Codec::InvalidType+ — these are wire violations per the
+      # SPEC's YieldResponse envelope contract.
+      def self.decode(bytes)
+        bytes = bytes.b
+        raise Codec::InvalidType, "YieldResponse must carry at least one byte" if bytes.empty?
+
+        tag = bytes.getbyte(0) # : Integer
+        body = bytes.byteslice(1, bytes.bytesize - 1) || +""
+
+        reject_dead_tag!(tag)
+        new(tag: tag, value: Codec::Decoder.decode(body))
+      end
+
+      def self.reject_dead_tag!(tag)
+        return if LIVE_TAGS.include?(tag)
+
+        msg = if tag == TAG_RESERVED
+                "YieldResponse tag 0x03 is reserved"
+              else
+                format(
+                  "YieldResponse tag 0x%02x is not recognised", tag
+                )
+              end
+        raise Codec::InvalidType, msg
+      end
+      private_class_method :reject_dead_tag!
+    end
+  end
+end