lex-llm 0.6.16 → 0.7.2

data/lib/legion/extensions/llm/inventory/evidence.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/inventory/errors'
+require 'legion/extensions/llm/inventory/immutable_value'
+require 'legion/extensions/llm/taxonomies'
+require 'legion/extensions/llm/capabilities'
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # Immutable operation, capability, and value evidence with
+        # authoritative/unknown semantics. See phase-1-lex-llm-additive.md
+        # section 9.
+        #
+        # For every evidence record `observed_at` is nil or a duplicated frozen
+        # Time used only for telemetry. It never participates in authority,
+        # ordering, freshness, recovery, or selection.
+        module Evidence
+          module_function
+
+          def normalize_observed_at(observed_at)
+            return nil if observed_at.nil?
+            raise Errors::ValidationError, 'observed_at must be a Time' unless observed_at.is_a?(::Time)
+
+            observed_at.dup.freeze
+          end
+
+          def validate_evidence_status(status:, allowed:)
+            raise Errors::ValidationError, "status must be one of #{allowed.inspect}" unless allowed.include?(status)
+
+            status
+          end
+
+          def validate_evidence_source(source:)
+            raise Errors::ValidationError, 'source is not one of Taxonomies::EVIDENCE_SOURCES' unless Taxonomies::EVIDENCE_SOURCES.include?(source)
+
+            source
+          end
+
+          def enforce_unknown_only_source!(status:, source:)
+            return unless Taxonomies::UNKNOWN_ONLY_EVIDENCE_SOURCES.include?(source)
+            return if status == :unknown
+
+            raise Errors::ValidationError, "source #{source} requires status :unknown"
+          end
+        end
+
+        # Evidence that a provider instance supports (or is not known to support)
+        # a canonical operation. `stream_chat` stays `stream_chat`; it never
+        # canonicalizes into capability `streaming`.
+        OperationEvidence = ::Data.define(:operation, :status, :source, :observed_at, :metadata) do
+          def initialize(operation:, status:, source:, observed_at: nil, metadata: {})
+            canonical_operation = Taxonomies.normalize_operation(value: operation, allow_aliases: false)
+            Evidence.validate_evidence_status(status: status, allowed: Taxonomies::OPERATION_EVIDENCE_STATES)
+            Evidence.validate_evidence_source(source: source)
+            Evidence.enforce_unknown_only_source!(status: status, source: source)
+
+            super(
+              operation: canonical_operation,
+              status: status,
+              source: source,
+              observed_at: Evidence.normalize_observed_at(observed_at),
+              metadata: ImmutableValue.copy_and_freeze(value: metadata, field: :metadata)
+            )
+          end
+
+          def supported? = status == :supported
+          def unsupported? = status == :unsupported
+          def unknown? = status == :unknown
+        end
+
+        # Evidence that a provider instance supports (or is not known to support)
+        # a canonical capability. Config permission, absent fields, default_false,
+        # failed probes, and guesses must be constructed as :unknown, never
+        # :unsupported.
+        CapabilityEvidence = ::Data.define(:capability, :status, :source, :observed_at, :metadata) do
+          def initialize(capability:, status:, source:, observed_at: nil, metadata: {})
+            canonical_capability = Legion::Extensions::Llm::Capabilities.canonical(capability)
+            raise Errors::ValidationError, "capability #{canonical_capability} is not canonical" unless Legion::Extensions::Llm::Capabilities::CANONICAL.include?(canonical_capability)
+
+            Evidence.validate_evidence_status(status: status, allowed: Taxonomies::CAPABILITY_EVIDENCE_STATES)
+            Evidence.validate_evidence_source(source: source)
+            Evidence.enforce_unknown_only_source!(status: status, source: source)
+
+            super(
+              capability: canonical_capability,
+              status: status,
+              source: source,
+              observed_at: Evidence.normalize_observed_at(observed_at),
+              metadata: ImmutableValue.copy_and_freeze(value: metadata, field: :metadata)
+            )
+          end
+
+          def supported? = status == :supported
+          def unsupported? = status == :unsupported
+          def unknown? = status == :unknown
+        end
+
+        # Evidence carrying a known scalar value (context limit, maximum output,
+        # embedding dimensions, tokenizer/estimator, immutable model revision) or
+        # an explicit :unknown. Each field uses a separate instance so one known
+        # field cannot make another field authoritative.
+        ValueEvidence = ::Data.define(:status, :value, :source, :observed_at, :metadata) do
+          def initialize(status:, source:, value: nil, observed_at: nil, metadata: {})
+            Evidence.validate_evidence_status(status: status, allowed: Taxonomies::VALUE_EVIDENCE_STATES)
+            Evidence.validate_evidence_source(source: source)
+            Evidence.enforce_unknown_only_source!(status: status, source: source)
+
+            case status
+            when :known
+              raise Errors::ValidationError, 'known ValueEvidence requires a non-nil value' if value.nil?
+            when :unknown
+              raise Errors::ValidationError, 'unknown ValueEvidence requires value: nil' unless value.nil?
+            end
+
+            copied_value = value.nil? ? nil : ImmutableValue.copy_and_freeze(value: value, field: :value)
+
+            super(
+              status: status,
+              value: copied_value,
+              source: source,
+              observed_at: Evidence.normalize_observed_at(observed_at),
+              metadata: ImmutableValue.copy_and_freeze(value: metadata, field: :metadata)
+            )
+          end
+
+          def known? = status == :known
+          def unknown? = status == :unknown
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/inventory/identity.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'legion/extensions/llm/inventory/errors'
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # Canonical field normalization plus the `off:v1:` and `lane:v1:`
+        # length-framed SHA-256 encoders/validators. See
+        # phase-1-lex-llm-additive.md section 8.
+        #
+        # Framing is binary: decimal UTF-8 byte length, ASCII ':', then the exact
+        # UTF-8 bytes. It never uses a delimiter join, Ruby hash order, object ID,
+        # or Ruby Hash#hash. Tier is never an identity input.
+        module Identity
+          module_function
+
+          def normalize_text(value:, field:)
+            raise Errors::ValidationError, "#{field} must be a String or Symbol" unless text_input?(value)
+
+            string = value.to_s
+            raise Errors::ValidationError, "#{field} is not valid UTF-8" unless valid_utf8?(string)
+
+            trimmed = utf8(string).strip
+            raise Errors::ValidationError, "#{field} must not be empty" if trimmed.empty?
+            raise Errors::ValidationError, "#{field} must be NFC-normalized" unless trimmed.unicode_normalized?(:nfc)
+
+            trimmed.freeze
+          end
+
+          def normalize_enum(value:, field:, allowed:)
+            raise Errors::ValidationError, "#{field} must be a String or Symbol" unless text_input?(value)
+
+            trimmed = value.to_s.strip
+            raise Errors::ValidationError, "#{field} must not be empty" if trimmed.empty?
+
+            candidate = trimmed.to_sym
+            raise Errors::ValidationError, "#{field} is not one of the allowed values" unless allowed.include?(candidate)
+
+            candidate
+          end
+
+          def length_frame(value:)
+            bytes = value.to_s.b
+            "#{bytes.bytesize}:".b + bytes
+          end
+
+          def offering_id(instance_key:, provider_native_key:)
+            digest = ::Digest::SHA256.hexdigest(
+              length_frame(value: instance_key.provider_family) +
+              length_frame(value: instance_key.instance_id) +
+              length_frame(value: provider_native_key)
+            )
+            "off:v1:#{digest}"
+          end
+
+          def lane_id(instance_key:, operation:, model:, offering_id:)
+            digest = ::Digest::SHA256.hexdigest(
+              "lane-v1\x00".b +
+              length_frame(value: instance_key.provider_family) +
+              length_frame(value: instance_key.instance_id) +
+              length_frame(value: operation) +
+              length_frame(value: model) +
+              length_frame(value: offering_id)
+            )
+            "lane:v1:#{digest}"
+          end
+
+          def validate_offering_id!(value:, instance_key:, provider_native_key:)
+            expected = offering_id(instance_key: instance_key, provider_native_key: provider_native_key)
+            raise Errors::ValidationError, 'offering_id does not reproduce from its identity fields' unless value == expected
+
+            value
+          end
+
+          def validate_lane_id!(value:, instance_key:, operation:, model:, offering_id:)
+            expected = lane_id(
+              instance_key: instance_key, operation: operation, model: model, offering_id: offering_id
+            )
+            raise Errors::ValidationError, 'lane_id does not reproduce from its identity fields' unless value == expected
+
+            value
+          end
+
+          def text_input?(value)
+            value.is_a?(::String) || value.is_a?(::Symbol)
+          end
+
+          def valid_utf8?(string)
+            [::Encoding::UTF_8, ::Encoding::US_ASCII].include?(string.encoding) && string.valid_encoding?
+          end
+
+          def utf8(string)
+            string.encoding == ::Encoding::UTF_8 ? string.dup : string.b.dup.force_encoding(::Encoding::UTF_8)
+          end
+
+          private_class_method :text_input?, :valid_utf8?, :utf8
+
+          # A mandatory, immutable provider_family + instance_id pair. Provider
+          # family alone is never executable; two instances of the same provider
+          # are independent targets. See section 8.1.
+          #
+          # instance_id is the operator's CONFIG NAME — the identity the router
+          # keys settings lookups (instances.<name>) by. physical_id is an
+          # optional SECONDARY field carrying the physical/derived id
+          # (e.g. "host:port" or "host:port/ak:<digest>") preserved for dedup
+          # and diagnostics. It is NOT identity: it never participates in
+          # equality, hashing, or registry-scope identity, so two config names
+          # pointing at the same endpoint stay distinct instances.
+          InstanceKey = ::Data.define(:provider_family, :instance_id, :physical_id) do
+            def initialize(provider_family:, instance_id:, physical_id: nil)
+              family = Identity.normalize_text(value: provider_family, field: :provider_family).downcase
+              raise Errors::ValidationError, 'provider_family must match /\A[a-z][a-z0-9_]*\z/' unless family.match?(/\A[a-z][a-z0-9_]*\z/)
+
+              instance = Identity.normalize_text(value: instance_id, field: :instance_id)
+              raise Errors::ValidationError, 'instance_id must not be the reserved value "default"' if instance == 'default'
+
+              physical = physical_id.nil? ? nil : Identity.normalize_text(value: physical_id, field: :physical_id)
+
+              super(provider_family: family.to_sym, instance_id: instance, physical_id: physical)
+            end
+
+            # Identity is exactly (provider_family, instance_id). The
+            # secondary physical_id never affects equality, hashing, or
+            # registry-scope identity.
+            def ==(other)
+              other.is_a?(self.class) && other.provider_family == provider_family && other.instance_id == instance_id
+            end
+            alias_method :eql?, :==
+
+            def hash
+              [self.class, provider_family, instance_id].hash
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/inventory/immutable_value.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/inventory/errors'
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # The single strict recursive copier/freezer for JSON-like metadata and
+        # collection fields. See phase-1-lex-llm-additive.md section 7.1.
+        #
+        # Records call this helper before `super`; they never implement a
+        # competing recursive-freeze helper. It recursively copies and freezes
+        # only nil, true/false, Symbol, Integer, finite Float, String, Time,
+        # Array, and Hash. Hash keys must be String or Symbol. Strings must be
+        # valid UTF-8. Time values are duplicated and frozen. Arrays and Hashes
+        # preserve order but never preserve a mutable nested reference. NaN,
+        # infinity, an unsupported object, a callable, or a cyclic Array/Hash
+        # raises ValidationError naming the field path.
+        module ImmutableValue
+          module_function
+
+          def copy_and_freeze(value:, field:)
+            deep_copy(value, field.to_s, [])
+          end
+
+          def deep_copy(value, path, ancestors)
+            case value
+            when nil, true, false, ::Symbol, ::Integer
+              value
+            when ::Float
+              raise Errors::ValidationError, "#{path} is not a finite Float" unless value.finite?
+
+              value
+            when ::String
+              raise Errors::ValidationError, "#{path} is not valid UTF-8" unless valid_utf8?(value)
+
+              value.dup.freeze
+            when ::Time
+              value.dup.freeze
+            when ::Array
+              copy_array(value, path, ancestors)
+            when ::Hash
+              copy_hash(value, path, ancestors)
+            else
+              raise Errors::ValidationError, "#{path} is an unsupported value type (#{value.class})"
+            end
+          end
+          # rubocop:enable Metrics/MethodLength
+
+          def copy_array(value, path, ancestors)
+            raise Errors::ValidationError, "#{path} contains a cyclic Array reference" if cyclic?(value, ancestors)
+
+            next_ancestors = ancestors + [value]
+            value.each_with_index.map do |element, index|
+              deep_copy(element, "#{path}[#{index}]", next_ancestors)
+            end.freeze
+          end
+
+          def copy_hash(value, path, ancestors)
+            raise Errors::ValidationError, "#{path} contains a cyclic Hash reference" if cyclic?(value, ancestors)
+
+            next_ancestors = ancestors + [value]
+            copied = {}
+            value.each do |key, element|
+              frozen_key = copy_key(key, path)
+              copied[frozen_key] = deep_copy(element, "#{path}.#{key}", next_ancestors)
+            end
+            copied.freeze
+          end
+
+          def copy_key(key, path)
+            case key
+            when ::Symbol
+              key
+            when ::String
+              raise Errors::ValidationError, "#{path} has a key that is not valid UTF-8" unless valid_utf8?(key)
+
+              key.dup.freeze
+            else
+              raise Errors::ValidationError, "#{path} has a non-String/Symbol key (#{key.class})"
+            end
+          end
+
+          def cyclic?(value, ancestors)
+            ancestors.any? { |ancestor| ancestor.equal?(value) }
+          end
+
+          def valid_utf8?(string)
+            [::Encoding::UTF_8, ::Encoding::US_ASCII].include?(string.encoding) && string.valid_encoding?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/inventory/probe_coordinator.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'legion/logging'
+require 'legion/extensions/llm/inventory/errors'
+require 'legion/extensions/llm/inventory/identity'
+require 'legion/extensions/llm/inventory/probe_token'
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # Enqueue-only probe handle with per-instance/revision coalescing and
+        # single-flight state. It owns no timer, thread, thread pool, provider
+        # API call, or registry transition. It is the `probe_request_handle`
+        # passed to Registry.claim_instance. See phase-1-lex-llm-additive.md
+        # section 13.2.
+        class ProbeCoordinator
+          include Legion::Logging::Helper
+
+          def initialize(instance_key:, enqueue:)
+            raise Errors::ValidationError, 'instance_key must be an InstanceKey' unless instance_key.is_a?(Identity::InstanceKey)
+            raise Errors::ValidationError, 'enqueue must be provided' if enqueue.nil?
+
+            @instance_key = instance_key
+            @enqueue = enqueue
+            @pending = nil
+            @in_flight_form = nil
+            @in_flight_request = nil
+            @mutex = Mutex.new
+          end
+
+          # Registry calls this after a root swap on dispatch_instance_unavailable.
+          def enqueue_probe_request(instance_key:, publisher_token_id:, unavailable_revision:, reason:)
+            request = ProbeRequest.new(
+              instance_key: instance_key, publisher_token_id: publisher_token_id,
+              unavailable_revision: unavailable_revision, reason: reason
+            )
+            raise Errors::ValidationError, 'instance_key mismatch' unless request.instance_key == @instance_key
+
+            to_enqueue = nil
+            @mutex.synchronize do
+              had_pending = !@pending.nil?
+              retain_greater(request)
+              to_enqueue = @pending if @in_flight_form.nil? && !had_pending
+            end
+            return true if to_enqueue.nil?
+
+            run_enqueue(to_enqueue)
+          end
+
+          def begin_probe(request: nil)
+            @mutex.synchronize do
+              return false unless @in_flight_form.nil?
+
+              if request.nil?
+                @in_flight_form = :cadence
+                @in_flight_request = nil
+              else
+                raise Errors::ValidationError, 'request must be a ProbeRequest' unless request.is_a?(ProbeRequest)
+                return false unless @pending && request.equal?(@pending)
+
+                @in_flight_form = :request
+                @in_flight_request = request
+                @pending = nil
+              end
+              true
+            end
+          end
+
+          def finish_probe(request: nil)
+            still_pending = nil
+            @mutex.synchronize do
+              validate_finish_form!(request)
+              @in_flight_form = nil
+              @in_flight_request = nil
+              still_pending = @pending
+            end
+            run_enqueue(still_pending) unless still_pending.nil?
+            still_pending
+          end
+
+          def pending?(unavailable_revision:)
+            @mutex.synchronize { !@pending.nil? && @pending.unavailable_revision == unavailable_revision }
+          end
+
+          def in_flight?
+            @mutex.synchronize { !@in_flight_form.nil? }
+          end
+
+          private
+
+          def retain_greater(request)
+            @pending = request if @pending.nil? || request.unavailable_revision > @pending.unavailable_revision
+          end
+
+          def validate_finish_form!(request)
+            if request.nil?
+              raise Errors::InvalidTransitionError, 'no cadence probe in flight' unless @in_flight_form == :cadence
+            else
+              raise Errors::InvalidTransitionError, 'finish request does not match the in-flight probe' unless @in_flight_form == :request && @in_flight_request.equal?(request)
+            end
+          end
+
+          def run_enqueue(request)
+            @enqueue.call(request: request) ? true : false
+          rescue StandardError => e
+            handle_exception(
+              e, handled: true, level: :warn, operation: 'llm.inventory.probe_coordinator.enqueue',
+                 provider_family: @instance_key.provider_family, instance_id: @instance_key.instance_id
+            )
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/inventory/probe_token.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'securerandom'
+require 'legion/extensions/llm/inventory/errors'
+require 'legion/extensions/llm/inventory/identity'
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # An opaque fenced publisher claim token. The raw secret is never
+        # serialized, logged, included in a record/snapshot/exception, returned
+        # separately, or compared for order. `publisher_id` and
+        # `publisher_token_id` are safe correlation/fencing values derived from
+        # the secret. See phase-1-lex-llm-additive.md section 11.1.
+        class PublisherToken
+          TOKEN_ID_DOMAIN = "publisher-token-id-v1\x00"
+
+          attr_reader :instance_key, :publisher_id, :publisher_token_id
+
+          def self.derive_token_id(secret)
+            "ptok:v1:#{::Digest::SHA256.hexdigest(TOKEN_ID_DOMAIN.b + secret.b)}"
+          end
+
+          # Factory used by the registry: builds a fresh secret and derives the
+          # public correlation IDs from it.
+          def self.issue(instance_key:)
+            secret = ::SecureRandom.hex(32)
+            new(
+              instance_key: instance_key, secret: secret,
+              publisher_id: "pub:v1:#{::SecureRandom.uuid}", publisher_token_id: derive_token_id(secret)
+            )
+          end
+
+          def initialize(instance_key:, secret:, publisher_id:, publisher_token_id:)
+            raise Errors::ValidationError, 'instance_key must be an InstanceKey' unless instance_key.is_a?(Identity::InstanceKey)
+            raise Errors::ValidationError, 'secret must be a nonempty String' unless nonempty_string?(secret)
+            raise Errors::ValidationError, 'publisher_id must be a pub:v1: String' unless publisher_id.to_s.start_with?('pub:v1:')
+            raise Errors::ValidationError, 'publisher_token_id must be a ptok:v1: String' unless publisher_token_id.to_s.start_with?('ptok:v1:')
+
+            @instance_key = instance_key
+            @secret = secret.b.dup.freeze
+            @publisher_id = publisher_id.dup.freeze
+            @publisher_token_id = publisher_token_id.dup.freeze
+            freeze
+          end
+
+          # Fenced validation: same InstanceKey, same public token ID, and a
+          # constant-time equal-length secret comparison using a local XOR
+          # accumulator (no ActiveSupport).
+          def authenticates?(other)
+            other.is_a?(PublisherToken) &&
+              instance_key == other.instance_key &&
+              publisher_token_id == other.publisher_token_id &&
+              secrets_match?(other)
+          end
+
+          def inspect
+            "#<#{self.class.name} instance_key=#{@instance_key.inspect} " \
+              "publisher_id=#{@publisher_id} publisher_token_id=#{@publisher_token_id} secret=[REDACTED]>"
+          end
+          alias to_s inspect
+
+          protected
+
+          def secret_bytes
+            @secret
+          end
+
+          private
+
+          def secrets_match?(other)
+            mine = @secret
+            theirs = other.secret_bytes
+            return false unless mine.bytesize == theirs.bytesize
+
+            accumulator = 0
+            mine.bytes.each_with_index { |byte, index| accumulator |= byte ^ theirs.getbyte(index) }
+            accumulator.zero?
+          end
+
+          def nonempty_string?(value)
+            value.is_a?(::String) && !value.empty?
+          end
+        end
+
+        # A single-use safe-readiness probe token. Carries no secret. See 11.2.
+        ProbeToken = ::Data.define(:token_id, :instance_key, :publisher_token_id, :started_availability_revision, :started_at) do
+          def self.issue(instance_key:, publisher_token_id:, started_availability_revision:, started_at:)
+            new(
+              token_id: "probe:v1:#{::SecureRandom.uuid}", instance_key: instance_key,
+              publisher_token_id: publisher_token_id, started_availability_revision: started_availability_revision,
+              started_at: started_at
+            )
+          end
+
+          def initialize(token_id:, instance_key:, publisher_token_id:, started_availability_revision:, started_at:)
+            raise Errors::ValidationError, 'instance_key must be an InstanceKey' unless instance_key.is_a?(Identity::InstanceKey)
+            raise Errors::ValidationError, 'token_id must be a probe:v1: String' unless token_id.to_s.start_with?('probe:v1:')
+            raise Errors::ValidationError, 'publisher_token_id must be a ptok:v1: String' unless publisher_token_id.is_a?(::String) && publisher_token_id.start_with?('ptok:v1:')
+            unless started_availability_revision.is_a?(::Integer) && !started_availability_revision.negative?
+              raise Errors::ValidationError, 'started_availability_revision must be a nonnegative Integer'
+            end
+            raise Errors::ValidationError, 'started_at must be a Time' unless started_at.is_a?(::Time)
+
+            super(
+              token_id: token_id.dup.freeze, instance_key: instance_key,
+              publisher_token_id: publisher_token_id.dup.freeze,
+              started_availability_revision: started_availability_revision, started_at: started_at.dup.freeze
+            )
+          end
+        end
+
+        # A process-local enqueue value asking the owning provider actor to run
+        # its safe readiness operation. Grants no registry mutation authority and
+        # carries no authorization secret. See section 11.2.
+        ProbeRequest = ::Data.define(:instance_key, :publisher_token_id, :unavailable_revision, :reason) do
+          def initialize(instance_key:, publisher_token_id:, unavailable_revision:, reason:)
+            raise Errors::ValidationError, 'instance_key must be an InstanceKey' unless instance_key.is_a?(Identity::InstanceKey)
+            raise Errors::ValidationError, 'publisher_token_id must be a nonempty ptok:v1: String' unless publisher_token_id.is_a?(::String) && publisher_token_id.start_with?('ptok:v1:')
+            raise Errors::ValidationError, 'unavailable_revision must be a positive Integer' unless unavailable_revision.is_a?(::Integer) && unavailable_revision.positive?
+
+            super(
+              instance_key: instance_key, publisher_token_id: publisher_token_id.dup.freeze,
+              unavailable_revision: unavailable_revision, reason: sanitized_reason(reason)
+            )
+          end
+
+          def sanitized_reason(reason)
+            unless reason.is_a?(::String) &&
+                   [::Encoding::UTF_8, ::Encoding::US_ASCII].include?(reason.encoding) && reason.valid_encoding?
+              raise Errors::ValidationError, 'reason must be a valid UTF-8 String'
+            end
+
+            trimmed = reason.strip
+            raise Errors::ValidationError, 'reason must not be empty' if trimmed.empty?
+            raise Errors::ValidationError, 'reason exceeds 1024 UTF-8 bytes' if trimmed.bytesize > 1024
+
+            trimmed.b.dup.force_encoding(::Encoding::UTF_8).freeze
+          end
+        end
+      end
+    end
+  end
+end