parse-stack-next 5.5.5 → 5.6.0

data/lib/parse/embeddings/binding_audit.rb

@@ -0,0 +1,211 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module Embeddings
+    # Checks that a `:vector` property's declared provider binding
+    # still matches the provider actually registered under that name.
+    #
+    # A `:vector` property may declare `provider:`, `model:`, and
+    # `dimensions:`. Only `provider:` was ever enforced. `dimensions:`
+    # is verified — but only against the vector a provider already
+    # returned, i.e. after the call has been made and paid for. And
+    # `model:` was never checked at all, which is the dangerous one: two
+    # generations of the same model family usually share a width
+    # (`voyage-3` and `voyage-3.5` are both 1024), so swapping the
+    # registered provider's model silently mixes incompatible
+    # embeddings into one index. Nothing raises, recall just quietly
+    # degrades, and the damage is only repairable by re-embedding.
+    #
+    # This module closes both gaps by comparing the declaration against
+    # the live provider BEFORE any request is issued.
+    #
+    # Auditing cannot happen at class-definition time: providers are
+    # registered by name and, as {Parse::Core::EmbedManaged} documents,
+    # registration may legitimately happen any time before the first
+    # save. So the audit runs lazily on each use and is also exposed as
+    # {.audit_all!} for an explicit boot-time or CI check.
+    module BindingAudit
+      # Raised when a property's declared binding disagrees with the
+      # registered provider.
+      class BindingMismatch < Parse::Embeddings::Error; end
+
+      # Raised when the audit cannot enumerate the classes it is meant
+      # to check. Distinct from {BindingMismatch}: nothing was found to
+      # be wrong, but nothing was verified either.
+      class DiscoveryFailed < Parse::Embeddings::Error; end
+
+      class << self
+        # Verify one property binding against a resolved provider.
+        #
+        # Deliberately NOT memoized. The check is a pair of comparisons
+        # against values already in memory, so caching it saves nothing
+        # measurable — while any cache key cheap enough to be worth
+        # computing (class name, provider object id) can go stale when a
+        # class is unloaded and redefined with a changed declaration, or
+        # when object ids are recycled. A validator that silently skips
+        # after a reload is worse than no validator, so correctness wins
+        # over an optimization with no observable benefit.
+        #
+        # @param klass [Class] the Parse::Object subclass.
+        # @param field [Symbol] the `:vector` property name.
+        # @param provider [Parse::Embeddings::Provider]
+        # @raise [BindingMismatch]
+        # @return [void]
+        def verify!(klass, field, provider)
+          declared = klass.vector_properties[field.to_sym]
+          return if declared.nil?
+
+          check!(klass, field, provider, declared)
+          nil
+        end
+
+        # Audit every declared binding whose provider is registered.
+        # Intended for boot or CI: it surfaces a drifted declaration
+        # before a single embedding is written, rather than on the
+        # first save that happens to touch it.
+        #
+        # @param classes [Array<Class>, nil] defaults to every
+        #   Parse::Object subclass carrying `:vector` properties.
+        # @param strict [Boolean] when true, an unregistered provider
+        #   is itself a failure; otherwise those bindings are skipped
+        #   (a provider may be registered later in boot).
+        # @return [Array<String>] human-readable problems, empty when clean.
+        def audit_all!(classes: nil, strict: false)
+          problems = []
+          begin
+            bindings = collect_bindings(classes)
+          rescue DiscoveryFailed => e
+            return [e.message]
+          end
+
+          bindings.each do |klass, field, declared|
+            provider_name = declared[:provider]
+            next if provider_name.nil?
+
+            begin
+              provider = Parse::Embeddings.provider(provider_name)
+            rescue Parse::Embeddings::ProviderNotRegistered => e
+              problems << "#{klass}##{field}: #{e.message}" if strict
+              next
+            end
+
+            begin
+              check!(klass, field, provider, declared)
+            rescue BindingMismatch => e
+              problems << e.message
+            end
+          end
+          problems
+        end
+
+        # {.audit_all!} that raises instead of returning problems.
+        #
+        # @raise [BindingMismatch] when any binding disagrees.
+        # @return [void]
+        def audit_all_or_raise!(classes: nil, strict: false)
+          problems = audit_all!(classes: classes, strict: strict)
+          return if problems.empty?
+
+          raise BindingMismatch,
+                "Parse::Embeddings binding audit failed:\n  - #{problems.join("\n  - ")}"
+        end
+
+        # Retained as a no-op for callers that invoked it when this
+        # module memoized verdicts.
+        # @return [void]
+        def reset!
+          nil
+        end
+
+        private
+
+        # Read a provider accessor, distinguishing "not implemented"
+        # from a legitimate nil. Returns `:unavailable` for the former
+        # so {#check!} can fail closed rather than skip the comparison.
+        def accessor(provider, method)
+          value = provider.public_send(method)
+          value.nil? ? :unavailable : value
+        rescue NotImplementedError, NoMethodError
+          :unavailable
+        end
+
+        def check!(klass, field, provider, declared)
+          declared_model = declared[:model]
+          if declared_model
+            actual_model = accessor(provider, :model_name)
+            # A declaration states a requirement. A provider that cannot
+            # answer what model it runs cannot satisfy it, so this fails
+            # closed — otherwise a custom provider without `model_name`
+            # would write same-width embeddings that are never checked
+            # against the declaration at all.
+            if actual_model == :unavailable
+              raise BindingMismatch,
+                    "#{klass}##{field} declares model: #{declared_model.inspect} but the " \
+                    "provider registered as #{declared[:provider].inspect} " \
+                    "(#{provider.class}) does not report a usable #model_name, so the " \
+                    "binding cannot be verified. Implement #model_name on the provider, " \
+                    "or drop `model:` from the property to opt out of the check."
+            end
+            if declared_model.to_s != actual_model.to_s
+              raise BindingMismatch,
+                    "#{klass}##{field} declares model: #{declared_model.inspect} but the " \
+                    "provider registered as #{declared[:provider].inspect} is running " \
+                    "#{actual_model.inspect}. Vectors from different models are not " \
+                    "comparable; embedding with the current provider would corrupt this " \
+                    "index. Update the declaration and re-embed, or register the declared " \
+                    "model."
+            end
+          end
+
+          declared_dims = declared[:dimensions]
+          if declared_dims
+            actual_dims = accessor(provider, :dimensions)
+            if actual_dims == :unavailable
+              raise BindingMismatch,
+                    "#{klass}##{field} declares dimensions: #{declared_dims} but the " \
+                    "provider registered as #{declared[:provider].inspect} " \
+                    "(#{provider.class}) does not report a usable #dimensions, so the " \
+                    "binding cannot be verified. #dimensions is required by the provider " \
+                    "protocol."
+            end
+            if declared_dims != actual_dims
+              raise BindingMismatch,
+                    "#{klass}##{field} declares dimensions: #{declared_dims} but the provider " \
+                    "registered as #{declared[:provider].inspect} emits #{actual_dims}-dim " \
+                    "vectors. Fix the declaration or configure the provider's width before " \
+                    "embedding."
+            end
+          end
+          nil
+        end
+
+        def collect_bindings(classes)
+          list = classes || default_classes
+          list.flat_map do |klass|
+            next [] unless klass.respond_to?(:vector_properties)
+            klass.vector_properties.map { |field, declared| [klass, field, declared] }
+          end
+        end
+
+        # Discovery must NOT swallow its own failure: an empty list from
+        # a crashed sweep is indistinguishable from a clean audit, so
+        # `audit_all_or_raise!` would report success having checked
+        # nothing. Failures propagate as {DiscoveryFailed} and
+        # {.audit_all!} converts them into a reported problem.
+        def default_classes
+          return [] unless defined?(Parse::Object)
+          ObjectSpace.each_object(Class).select do |k|
+            k < Parse::Object && k.respond_to?(:vector_properties) &&
+              !k.vector_properties.empty?
+          end
+        rescue StandardError => e
+          raise DiscoveryFailed,
+                "Parse::Embeddings::BindingAudit could not enumerate Parse::Object " \
+                "subclasses (#{e.class}: #{e.message}); the audit checked nothing. " \
+                "Pass `classes:` explicitly to audit a known set."
+        end
+      end
+    end
+  end
+end

data/lib/parse/embeddings/media_file.rb

@@ -0,0 +1,136 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module Embeddings
+    # A file-backed image or video input that is **streamed** into the
+    # request body rather than read into memory.
+    #
+    # This is the memory-safe counterpart to
+    # {ImageFetch::FetchedImage}, which holds raw bytes. A MediaFile
+    # holds only a path, a sniffed MIME type, and a byte count; the
+    # bytes are read and base64-encoded incrementally by
+    # {StreamingBody} while the request is being written to the socket.
+    # Peak memory stays at {StreamingBody::READ_CHUNK} no matter how
+    # large the file is, which is what makes video viable on a small
+    # dyno.
+    #
+    # Only the first 16 bytes are read at construction time, to sniff
+    # the container. The `Content-Type` header and the filename
+    # extension are never consulted.
+    #
+    # @example stream a local image
+    #   img = Parse::Embeddings::MediaFile.image("diagram.png")
+    #   provider.embed_image([img])
+    #
+    # @example stream a local video
+    #   clip = Parse::Embeddings::MediaFile.video("demo.mp4")
+    #   provider.embed_video([clip])
+    class MediaFile
+      # Voyage documents 20 MB per image and 20 MB per video.
+      # Overridable via {Parse::Embeddings.max_media_bytes=}.
+      DEFAULT_MAX_MEDIA_BYTES = 20 * 1024 * 1024
+
+      # Raised when a file exceeds {Parse::Embeddings.max_media_bytes}.
+      class TooLarge < Parse::Embeddings::Error; end
+
+      # @return [String] absolute path to the backing file.
+      attr_reader :path
+      # @return [String] sniffed MIME type.
+      attr_reader :mime_type
+      # @return [Integer] size in bytes, captured at construction.
+      attr_reader :byte_size
+      # @return [Symbol] `:image` or `:video`.
+      attr_reader :kind
+
+      class << self
+        # Wrap a local image file. Verifies the magic bytes against
+        # {Parse::Embeddings.allowed_image_types}.
+        #
+        # @param path [String]
+        # @return [MediaFile]
+        # @raise [ImageFetch::InvalidImageType]
+        def image(path)
+          header = read_header(path)
+          mime = ImageFetch.sniff_mime(header)
+          if mime.nil?
+            raise ImageFetch::InvalidImageType.new(:unknown_magic,
+              "Parse::Embeddings::MediaFile.image: #{path} matches no supported image " \
+              "format (JPEG/PNG/GIF/WebP).")
+          end
+          allowed = Parse::Embeddings.allowed_image_types
+          unless allowed.include?(mime)
+            raise ImageFetch::InvalidImageType.new(:type_not_allowed,
+              "Parse::Embeddings::MediaFile.image: sniffed type #{mime.inspect} is not in " \
+              "Parse::Embeddings.allowed_image_types (#{allowed.inspect}).")
+          end
+          new(path: path, mime_type: mime, kind: :image)
+        end
+
+        # Wrap a local video file. Verifies the magic bytes against
+        # {Parse::Embeddings.allowed_video_types}.
+        #
+        # @param path [String]
+        # @return [MediaFile]
+        # @raise [VideoSource::InvalidVideoType]
+        def video(path)
+          header = read_header(path)
+          new(path: path, mime_type: VideoSource.verify!(header), kind: :video)
+        end
+
+        private
+
+        # Read only enough bytes to sniff a container. Deliberately
+        # tiny — the whole point of this class is to never hold the
+        # file. A file shorter than this is passed through as-is so the
+        # sniffers can reject it with their own error.
+        def read_header(path)
+          unless ::File.file?(path)
+            raise ArgumentError,
+                  "Parse::Embeddings::MediaFile: #{path.inspect} is not a readable file."
+          end
+          ::File.open(path, "rb") { |f| f.read(16).to_s }
+        end
+      end
+
+      def initialize(path:, mime_type:, kind:)
+        @path = ::File.expand_path(path)
+        @mime_type = mime_type
+        @kind = kind
+        @byte_size = ::File.size(@path)
+        if @byte_size.zero?
+          raise ArgumentError,
+                "Parse::Embeddings::MediaFile: #{path.inspect} is empty."
+        end
+        cap = Parse::Embeddings.max_media_bytes
+        if @byte_size > cap
+          raise TooLarge,
+                "Parse::Embeddings::MediaFile: #{path.inspect} is #{@byte_size} bytes, over " \
+                "the #{cap}-byte limit (Parse::Embeddings.max_media_bytes). Voyage rejects " \
+                "media above 20 MB — downscale or re-encode before embedding."
+        end
+      end
+
+      # The `data:` URI prefix that precedes the streamed base64 in the
+      # wire body. The payload itself is never concatenated here.
+      #
+      # @return [String]
+      def data_uri_prefix
+        "data:#{mime_type};base64,"
+      end
+
+      # Segment descriptor consumed by {StreamingBody}.
+      #
+      # @return [Hash]
+      def stream_segment
+        { path: @path, size: @byte_size }
+      end
+
+      def inspect
+        "#<Parse::Embeddings::MediaFile kind=#{@kind} mime_type=#{@mime_type.inspect} " \
+        "bytes=#{@byte_size} path=#{@path.inspect}>"
+      end
+      alias_method :to_s, :inspect
+    end
+  end
+end

data/lib/parse/embeddings/provider.rb

@@ -24,6 +24,7 @@ module Parse
     # Subclasses MAY override:
     #
     # * {#embed_image}      — v5.1 (multimodal); default `NotImplementedError`
+    # * {#embed_video}      — v5.6 (multimodal); default `NotImplementedError`
     # * {#embed_batch_size} — provider-recommended batch size hint
     # * {#max_input_tokens} — chunker hint
     # * {#normalize?}       — whether output is unit-normalized
@@ -76,6 +77,44 @@ module Parse
         raise NotImplementedError, "#{self.class} does not support image embedding"
       end
 
+      # Embed video sources. Same contract and default posture as
+      # {#embed_image}: providers that do not offer video leave this
+      # raising, and callers discover support through {#modalities}
+      # rather than by rescuing.
+      #
+      # Video payloads are large enough that holding one in memory is a
+      # real operational risk, so the two source forms concrete
+      # providers should accept are:
+      #
+      # * a URL String, forwarded for provider-side fetch after
+      #   {Parse::Embeddings.validate_image_url!} screens it (the SDK
+      #   never downloads the video), and
+      # * a {Parse::Embeddings::MediaFile}, streamed into the request
+      #   body by {Parse::Embeddings::StreamingBody} without ever being
+      #   fully resident.
+      #
+      # Concrete overrides must accept `allow_insecure:` explicitly or
+      # absorb it via `**opts` — see {#embed_image} for why.
+      #
+      # @param sources [Array<String, Parse::Embeddings::MediaFile>]
+      # @param input_type [Symbol] `:search_query` or `:search_document`.
+      # @param allow_insecure [Boolean] forwarded to the URL validator.
+      # @param opts [Hash] provider-specific options.
+      # @return [Array<Array<Float>>] vectors aligned 1:1 with `sources`.
+      # @raise [NotImplementedError] unless the provider offers video.
+      def embed_video(sources, input_type: :search_document, allow_insecure: false, **opts)
+        raise NotImplementedError, "#{self.class} does not support video embedding"
+      end
+
+      # @return [Boolean] whether this provider accepts `modality`.
+      #   Prefer this over rescuing {NotImplementedError} — it answers
+      #   the question without issuing a call.
+      #
+      # @param modality [Symbol] one of `:text`, `:image`, `:video`.
+      def supports_modality?(modality)
+        modalities.include?(modality.to_sym)
+      end
+
       # Batched text embedding. Splits `strings` into chunks of size
       # {#embed_batch_size} (or returns a single-shot call when nil) and
       # concatenates results. Concrete providers should override only

data/lib/parse/embeddings/streaming_body.rb

@@ -0,0 +1,170 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "base64"
+
+module Parse
+  module Embeddings
+    # An IO-shaped request body that splices base64-encoded files into
+    # a JSON envelope **without ever holding a whole file in memory**.
+    #
+    # Multimodal endpoints want one JSON document with the media inlined
+    # as a `data:` URI. Building that with `to_json` costs roughly 2.4x
+    # the media size resident (raw bytes + the 1.33x base64 copy + the
+    # serialized JSON String), which is enough to OOM a small dyno on a
+    # single moderate video. This class instead emits the body as a
+    # stream of segments — literal JSON fragments interleaved with
+    # files that are read and encoded {READ_CHUNK} bytes at a time —
+    # so peak memory is bounded by the chunk size regardless of how
+    # large the media is, and nothing is spilled to disk either.
+    #
+    # Faraday's net_http adapter assigns any body responding to `#read`
+    # to `Net::HTTP::Request#body_stream`, which pulls it incrementally.
+    # {#size} is exact, so callers can set `Content-Length` and avoid
+    # chunked transfer encoding (which some API gateways reject).
+    #
+    # Base64 is spliced directly into the JSON string literal with no
+    # escaping: the alphabet (`A-Za-z0-9+/=`) contains no character
+    # that JSON requires escaping, so this is safe by construction.
+    class StreamingBody
+      # Bytes read from a source file per fill. MUST stay a multiple of
+      # 3 so each chunk encodes to a padding-free base64 block and the
+      # concatenation is byte-identical to encoding the whole file at
+      # once. Only the final (short) chunk may carry `=` padding.
+      READ_CHUNK = 57 * 1024
+
+      # Raised when a segment's file changes size between the
+      # {#size} calculation and the actual read, which would desync
+      # `Content-Length` from the emitted body.
+      class SizeMismatch < Parse::Embeddings::Error; end
+
+      # @param segments [Array<String, Hash>] literal Strings are
+      #   emitted verbatim; Hashes of the form
+      #   `{ path: String, size: Integer }` are base64-streamed.
+      def initialize(segments)
+        @segments = segments.map do |seg|
+          case seg
+          when String then seg.dup.force_encoding(Encoding::BINARY)
+          when Hash
+            unless seg[:path].is_a?(String) && seg[:size].is_a?(Integer)
+              raise ArgumentError,
+                    "Parse::Embeddings::StreamingBody: file segment needs :path and :size."
+            end
+            seg
+          else
+            raise ArgumentError,
+                  "Parse::Embeddings::StreamingBody: segment must be a String or " \
+                  "{path:, size:} Hash (got #{seg.class})."
+          end
+        end
+        rewind
+      end
+
+      # Exact byte length of the fully-emitted body. Base64 expands
+      # every 3 input bytes to 4 output bytes, padded up.
+      #
+      # @return [Integer]
+      def size
+        @size ||= @segments.sum do |seg|
+          seg.is_a?(String) ? seg.bytesize : 4 * ((seg[:size] + 2) / 3)
+        end
+      end
+      alias_method :length, :size
+
+      # @param len [Integer, nil] bytes wanted; nil reads to the end
+      #   (which defeats the memory bound — Net::HTTP always passes a
+      #   length, so this is only for completeness).
+      # @param out [String, nil] optional output buffer to fill.
+      # @return [String, nil] nil once exhausted, per IO#read semantics.
+      def read(len = nil, out = nil)
+        fill(len)
+        if @buffer.empty?
+          out&.clear
+          return len.nil? ? "" : nil
+        end
+
+        chunk =
+          if len.nil?
+            b = @buffer
+            @buffer = +""
+            b
+          else
+            @buffer.slice!(0, len)
+          end
+
+        if out
+          out.replace(chunk)
+          out
+        else
+          chunk
+        end
+      end
+
+      # Reset to the start so the body can be replayed (Net::HTTP
+      # rewinds `body_stream` when it retries a request).
+      #
+      # @return [void]
+      def rewind
+        close
+        @buffer = +""
+        @index = 0
+        @io = nil
+        nil
+      end
+
+      # @return [void]
+      def close
+        @io&.close
+        @io = nil
+        nil
+      end
+
+      private
+
+      # Top up @buffer until it holds `len` bytes or the segments run
+      # out. Reads at most one READ_CHUNK per iteration, so peak
+      # memory is READ_CHUNK * 4/3 plus whatever the caller asked for.
+      def fill(len)
+        loop do
+          return if len && @buffer.bytesize >= len
+          return if @index >= @segments.length
+
+          seg = @segments[@index]
+          if seg.is_a?(String)
+            @buffer << seg
+            @index += 1
+            next
+          end
+
+          @io ||= begin
+            f = ::File.open(seg[:path], "rb")
+            actual = f.size
+            if actual != seg[:size]
+              f.close
+              raise SizeMismatch,
+                    "Parse::Embeddings::StreamingBody: #{seg[:path]} is #{actual} bytes but " \
+                    "#{seg[:size]} was declared; the file changed underneath the request."
+            end
+            f
+          end
+
+          data = @io.read(READ_CHUNK)
+          if data.nil? || data.empty?
+            @io.close
+            @io = nil
+            @index += 1
+            next
+          end
+          @buffer << Base64.strict_encode64(data)
+          # A short read means EOF; close now so the padding lands and
+          # the next iteration advances to the following segment.
+          if data.bytesize < READ_CHUNK
+            @io.close
+            @io = nil
+            @index += 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/parse/embeddings/video_source.rb

@@ -0,0 +1,120 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "base64"
+
+module Parse
+  module Embeddings
+    # Value objects and magic-byte verification for video inputs to
+    # multimodal embedding providers.
+    #
+    # This mirrors {ImageFetch} deliberately — same sniff-then-verify
+    # discipline, same refusal to trust a `Content-Type` header — but
+    # it deliberately ships NO byte-holding value object and NO
+    # `fetch!` counterpart. Video payloads are large enough that
+    # holding one in memory can exhaust a small dyno, so both supported
+    # paths avoid it:
+    #
+    # * **local file** — wrap with {Parse::Embeddings::MediaFile.video},
+    #   which reads only the 16-byte header. The bytes are base64-
+    #   streamed into the request by {StreamingBody} at send time.
+    # * **URL** — pass the URL String straight to `embed_video`, which
+    #   validates it through {Parse::Embeddings.validate_image_url!}
+    #   (a generic URL-safety guard despite the name: CIDR screen, port
+    #   and host allowlist, sentinel-gated egress) and lets the
+    #   provider do the fetch. The SDK never downloads the video.
+    module VideoSource
+      # Raised when bytes fail verification — unknown magic, or a
+      # sniffed type outside the allowlist. Carries a `:reason` tag
+      # (`:empty`, `:unknown_magic`, `:type_not_allowed`) matching
+      # {ImageFetch::InvalidImageType}'s convention.
+      class InvalidVideoType < Parse::Embeddings::Error
+        # @return [Symbol] failure-mode tag.
+        attr_reader :reason
+        def initialize(reason, message)
+          @reason = reason
+          super(message)
+        end
+      end
+
+      # MIME types accepted by default. Voyage documents MP4 as the
+      # only supported video container, and the live API rejects WebM
+      # and QuickTime payloads outright — so accepting them here would
+      # only trade a clear local error for an opaque provider 400.
+      # {.sniff_mime} still *recognizes* those containers so the
+      # rejection can name what was actually supplied.
+      DEFAULT_ALLOWED_VIDEO_TYPES = %w[video/mp4].freeze
+
+      # ISO Base Media major brands, split by the MIME type they imply.
+      # An `ftyp` box alone does NOT mean MP4 — QuickTime and the
+      # audio-only profiles share the container — so brands are matched
+      # explicitly and an unknown brand sniffs as nil rather than being
+      # assumed to be MP4.
+      #
+      # `M4A` is deliberately absent: it is Apple's audio-only profile,
+      # and admitting it here would let an audio file pass as video and
+      # be sent to a provider that accepts neither.
+      MP4_BRANDS = %w[isom iso2 iso4 iso5 iso6 mp41 mp42 avc1 dash mmp4 M4V].freeze
+      QUICKTIME_BRANDS = %w[qt].freeze
+
+      module_function
+
+      # Determine a video's MIME type from its leading magic bytes.
+      # Returns nil for anything unrecognized — callers must treat nil
+      # as a refusal and never fall back to extension or header typing.
+      #
+      # @param bytes [String] raw video bytes (at least the first 12).
+      # @return [String, nil] sniffed MIME type, or nil when unknown.
+      def sniff_mime(bytes)
+        return nil unless bytes.is_a?(String) && bytes.bytesize >= 12
+        b = bytes.byteslice(0, 16).force_encoding(Encoding::BINARY)
+
+        # Matroska / WebM share an EBML header; WebM is the profile
+        # every multimodal provider documents, so report it as WebM.
+        return "video/webm" if b.start_with?("\x1A\x45\xDF\xA3".b)
+
+        # ISO Base Media File Format: a size-prefixed `ftyp` box. The
+        # 4-byte major brand at offset 8 separates QuickTime from MP4.
+        # Unknown brands return nil — guessing "MP4" for an arbitrary
+        # ISO-BMFF file sends the provider something it will reject.
+        if b.byteslice(4, 4) == "ftyp".b
+          brand = b.byteslice(8, 4).to_s.strip
+          return "video/quicktime" if QUICKTIME_BRANDS.include?(brand)
+          return "video/mp4" if MP4_BRANDS.include?(brand)
+          return nil
+        end
+
+        nil
+      end
+
+      # Sniff the magic bytes and check the allowlist. Only the leading
+      # bytes are inspected, so callers may pass a short header slice
+      # rather than the whole file — which is what
+      # {Parse::Embeddings::MediaFile.video} does.
+      #
+      # @param bytes [String] leading video bytes (at least 12).
+      # @return [String] the sniffed MIME type.
+      # @raise [InvalidVideoType]
+      def verify!(bytes)
+        if bytes.nil? || bytes.empty?
+          raise InvalidVideoType.new(:empty,
+            "Parse::Embeddings::VideoSource: video payload is empty.")
+        end
+        mime = sniff_mime(bytes)
+        if mime.nil?
+          raise InvalidVideoType.new(:unknown_magic,
+            "Parse::Embeddings::VideoSource: leading bytes match no supported video " \
+            "container (MP4/QuickTime/WebM). The Content-Type header is not consulted — " \
+            "unrecognized content is refused outright.")
+        end
+        allowed = Parse::Embeddings.allowed_video_types
+        unless allowed.include?(mime)
+          raise InvalidVideoType.new(:type_not_allowed,
+            "Parse::Embeddings::VideoSource: sniffed type #{mime.inspect} is not in " \
+            "Parse::Embeddings.allowed_video_types (#{allowed.inspect}).")
+        end
+        mime
+      end
+    end
+  end
+end