search-engine-for-typesense 30.8.24 → 30.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db1ad7dbacfe019861ce7dbe7f3511326d67f0afc8bbf22ed2929cdb300797ad
-  data.tar.gz: 5bfafebc3623ee781a1c519c799621bfb8ca62b19f21e6370e79d4d165bc3999
+  metadata.gz: 2f5d1b6315a75f241c80d16c1f69727fed0ceef2edabb8ce774d33c348756a59
+  data.tar.gz: fbb2364ac8afc372ff0bbcb8f70174874ab190e226f6d08e1e747b018be8259b
 SHA512:
-  metadata.gz: b1ce3108ba2a8ef685803cf06264e88a9565dfe7e640f983465f198a03ba2f5b4cf059555c00b2e1016fa38f49aadb6be6bc7bcc538b5564a46c922e103f6db5
-  data.tar.gz: 9a2ddb0b81c46d8c81ce06e622f4b16adf1f81f50a4f4ccf2ff756c3d2542cf8d90111d31b7412f77e88dd441d7429106779457033e30bfc0c8d6b12e169342f
+  metadata.gz: 1db71818517bd5dd234a43ebfe63f1b9affa33b4fcb0f6a15914cb6bcd55a3a6844ba8a87e68ead1bbc81a3a87dbe3dba2d845f9ba8c4da6d3251ed877755c5b
+  data.tar.gz: 56a54cdd5a7a0fdf3566c021788ba9f4d54aa9311f7df508b8b9e99c5d7010c9ecd26cf2d83cc219625a48d7738883e03c49360c9d7c4d256f4fc48d173e315b

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 30.9.1
+
+- Serialize PostgreSQL delivery discovery across schedulers and workers and check delivery membership
+  by event and target. Hosts can enable checkpointed scans to bound discovery on large outboxes.
+- Execute advisory locks and delivery cutover polls on the database when Rails query caching is enabled.
+
+## 30.9.0
+
+- Qualify geo/vector search and native caching against Typesense 30.2 while keeping the gem major
+  version aligned with the Typesense major version.
+- Expose model-level geo/vector query methods, preserve external hybrid weights and historical query
+  boundaries, and sort the active vector query with Typesense's native distance token.
+- Validate finite real vectors, declared field types/dimensions and integer options before execution.
+  Preserve backend vector distance on flat, grouped and multi-search hits.
+- Redact scientific-notation vector components and forward single/multi-search cache options through
+  the Ruby SDK's request parameters.
+- Preserve caller-owned history strings and IDs, reject invalid scalar conversions consistently, and
+  mask malformed vector values. Align single-search adapters, telemetry and shell-quoted cURL previews
+  with GET requests and URL cache controls.
+- Keep stale-deletion estimates uncached so maintenance previews observe current documents.
+- Add database-free query examples and isolated Typesense 30.2 integration checks, including scoped-key
+  cache isolation and opt-in model-backed search. Upgrade older servers before using scoped-key caching.
+
 ## 30.8.24
 
 - Adopt `{typesense_major}.{gem_minor}.{gem_patch}` versioning, omitting the Typesense minor component.

data/README.md

@@ -8,15 +8,18 @@ Mountless Rails::Engine for [Typesense](https://typesense.org). Expressive Relat
 
 ## Versioning
 
-Versions use `{typesense_major}.{gem_minor}.{gem_patch}`. The first component identifies the targeted Typesense server major version; the remaining components track gem enhancements and fixes independently of Typesense minor releases.
+Versions use `{typesense_major}.{gem_minor}.{gem_patch}`. The first component identifies the targeted
+Typesense server major version; the remaining components track gem enhancements and fixes independently
+of Typesense minor releases.
 
-Example: `30.8.24` targets Typesense `30.x`. Typesense minor versions are not encoded in the gem version.
+Gem `30.9.0` targets Typesense **30.x** and is tested against **30.2**. Typesense minor versions are not
+encoded in the gem version.
 
 ## Quickstart
 
 ```ruby
 # Gemfile
-gem "search-engine-for-typesense"
+gem "search-engine-for-typesense", "~> 30.9"
 ```
 
 ```ruby
@@ -180,8 +183,56 @@ SearchEngine::Venue
 # Access geo distance on results (present when order_geo is used)
 result = SearchEngine::Venue.all.order_geo(:location, from: { lat: 54.69, lng: 25.28 }).execute
 result.hits.first.geo_distance_meters # => { "location" => 1234 }
+
+# External vectors: supply embeddings generated by your application
+class SearchEngine::Article < SearchEngine::Base
+  collection :articles
+  identify_by :id
+  attribute :title, :string
+  embedding :embedding, suffix: false, num_dim: 3
+  query_by :title
+end
+
+result = SearchEngine::Article
+  .search('chair')
+  .vector_search(query: [1, 0, 0], alpha: 0.8, k: 20)
+  .order(vector_distance: :asc)
+  .execute
+result.hits.first.vector_distance # Exact backend distance, including 0
+SearchEngine::Article.find_similar('article-42', k: 20).to_a
+```
+
+`where_geo`, `order_geo`, `order_eval`, `vector_search` and `find_similar` work directly on models
+and on relations. They build lazy queries. Vector distance ordering uses the active query's native
+`_vector_distance` sort; it does not generate another embedding. The metadata reader is present when
+the backend supplies a distance, including grouped and multi-search hits. It takes precedence over
+a same-named document reader; the original document remains in `result.raw`.
+
+Vectors must contain finite real numbers and match declared dimensions. Integer options (`k`, `ef`,
+`flat_search_cutoff`) reject fractional values and accept integer strings. Historical queries preserve
+commas, parentheses and brackets; colons, backticks, control characters and surrounding whitespace
+raise `InvalidVectorQuery`. Similarity IDs reject commas, colons, parentheses, control characters and
+surrounding whitespace. Weight sums keep the configurable wrapper tolerance (default `0.01`), but
+Typesense 30.1/30.2 require a sum of 1.0; a server rejection propagates as `Errors::Api`.
+
+Typesense **30.2** is the tested server baseline. Geo, external vectors, auto-embedded hybrid search,
+historical queries and native caching are checked against that version. Earlier 30.1 qualification
+exposed the scoped-cache isolation defect described below; upgrade before using scoped-key caching.
+See the [vector guide](https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30/vector-search)
+for auto-embedding declarations and query modes.
+
+Run the database-free examples from the gem root:
+
+```bash
+bundle exec ruby examples/demo_shop/bin/query_smoke
 ```
 
+This compiles geo/vector requests and checks metadata fixtures without HTTP requests or model downloads.
+See [the demo instructions](examples/demo_shop/README.md#query-examples) for explicitly isolated live execution,
+including highlighting through `Client#search` and `hit.snippet_for`.
+CI uses a disposable `typesense/typesense:30.2` service for geo, vector, cache and live CLI checks,
+including the built-in embedding model. The default unit suite runs separately without integration ENV.
+
 `upsert_bulk` defaults to `on_failure: :raise`. Use the exact symbol `:return` when the caller needs to
 handle valid Typesense row failures itself. Malformed responses and response/document count mismatches always
 raise in either mode; the gem never guesses which submitted document a missing response row belongs to.
@@ -207,6 +258,28 @@ You can control this explicitly with:
 
 If you set `SearchEngine.configure { |c| c.client = ... }`, the custom client is always used.
 
+## Native search caching
+
+The gem defaults to `use_cache: true` and `cache_ttl_s: 60`. Single-search cache options are sent as
+GET parameters; multi-search options apply to the whole request URL, outside individual search bodies.
+Use `Model.cache(false).count` or `.to_a` for fresh maintenance reads.
+
+On Typesense 30.1/30.2, cached responses remained stale after document writes and alias swaps until
+expiry or explicit clearing. A direct key's URL `cache_ttl` did not override the native default;
+embed `cache_ttl` in a scoped search key when controlling TTL. Revoked keys fail authentication even
+when a matching response is cached.
+
+**Typesense 30.1 has a scoped-cache isolation defect:** identical single/multi-search requests with
+different scoped filters can receive each other's cached results. The same checks pass on 30.2.
+On 30.1, set `c.use_cache = false` or use `.cache(false)` for scoped authorization; upgrade to 30.2
+before enabling it. The integration tests retain strict isolation assertions and expose this server
+failure rather than skipping it. The gem's existing global cache default is unchanged.
+
+`SearchEngine::Cache.clear` clears the contacted server's native search cache. For incremental outbox
+writes, `postgres_outbox.clear_cache_after_write` remains opt-in: clearing occurs before database
+acknowledgement, and clearing failures propagate. No Redis response-cache layer is required for
+sharing cached searches across application processes reaching the same Typesense node.
+
 ## Async partition indexing
 
 Async partition indexing is an advanced opt-in mode for partitioned full indexing. The default remains
@@ -492,6 +565,22 @@ target-specific status, retry, lock, and queue state for each logical event. Add
 `create_search_engine_outbox_drain_slots` in that delivery-target migration so the drain enqueuer can cap
 queued and running drain jobs per target.
 
+Concurrent listener, scheduler and worker calls share one nonblocking PostgreSQL transaction lock for
+delivery discovery on each events table. Other callers can keep claiming existing deliveries.
+For large histories, create a checkpoint table in a migration with
+`create_search_engine_outbox_materialization_cursors`, then set
+`c.postgres_outbox.materialization_cursor_table_name = 'search_engine_outbox_materialization_cursors'`.
+Run the migration before starting consumers with this setting.
+
+With checkpoints, each discovery call checks at most 1,000 IDs around the forward position and
+1,000 historical IDs against the requested targets. The forward scan overlaps its previous
+range to catch nearby out-of-order commits. Each target set maintains its own position. A
+transaction that commits farther behind, or an older event that becomes due, can wait until
+the historical scan revisits its ID. Sweep time depends on retained history and polling rate.
+Collection batch quotas and the latest-event rule still govern which deliveries may be created.
+Without a configured checkpoint table the existing full-history discovery uses indexed per-event
+delivery checks and the same concurrency lock.
+
 Drain slots are a generic backpressure mechanism for delivery-target mode. On each listener or polling
 wakeup, the enqueuer materializes missing delivery rows, acquires idle slots from
 `c.postgres_outbox.drain_slot_table_name`, and enqueues one drain job per acquired slot. If all slots for a

data/lib/search_engine/base/relation_delegation.rb

@@ -19,6 +19,7 @@ module SearchEngine
         # Delegate materializers and query dsl to `.all` so callers can do `Model.first` etc.
         %i[
           where rewhere merge order preset ranking prefix search
+          where_geo order_geo order_eval vector_search find_similar
           pin hide curate clear_curation
           facet_by facet_query group_by unscope
           limit offset page per_page per options cache

data/lib/search_engine/client/http_adapter.rb

@@ -31,7 +31,7 @@ module SearchEngine
       # {Response#body}.
       #
       # Supported forms (current usage):
-      # - POST `/collections/:collection/documents/search` (with `common_params`)
+      # - GET `/collections/:collection/documents/search` (with URL search/cache parameters)
       #
       # @param request [SearchEngine::Client::RequestBuilder::Request] normalized request
       # @return [Response] response wrapper with status, headers and raw body
@@ -40,22 +40,14 @@ module SearchEngine
       def perform(request)
         method = request.http_method.to_sym
         path = request.path.to_s
-        if method == :post && path.match?(%r{\A/collections/[^/]+/documents/search\z})
+        if method == :get && path.match?(%r{\A/collections/[^/]+/documents/search\z})
           collection = path.split('/')[2]
           docs = @typesense.collections[collection].documents
-          begin
-            params = docs.method(:search).parameters
-            supports_common = params.any? { |(kind, _)| %i[key keyreq keyrest].include?(kind) }
-          rescue StandardError
-            supports_common = false
-          end
-          raw = supports_common ? docs.search(request.body, common_params: request.params) : docs.search(request.body)
+          raw = docs.search(request.params)
           # The official client returns parsed JSON (Hash). No headers/status exposed here.
           return Response.new(status: 200, headers: {}, body: raw)
         end
 
-        # Fallback: attempt a generic call via low-level typesense endpoint access if available.
-        # This keeps adapter permissive for future endpoints without adding Faraday here.
         raise ArgumentError, "Unsupported request path for adapter: #{request.http_method} #{request.path}"
       end
     end

data/lib/search_engine/client/request_builder.rb

@@ -63,17 +63,15 @@ module SearchEngine
       # @see `https://typesense.org/docs/latest/api/documents.html#search-document`
       def self.build_search(collection:, compiled_params:, url_opts: {})
         name = collection.to_s
-        body_hash = sanitize_body_params(compiled_params.to_h)
-        # Ensure deterministic ordering even after sanitization
-        body_json = SearchEngine::CompiledParams.from(body_hash).to_json
+        query_params = sanitize_body_params(compiled_params.to_h).merge(url_opts || {})
 
         Request.new(
-          http_method: :post,
+          http_method: :get,
           path: COLLECTIONS_PREFIX + name + DOCUMENTS_SEARCH_SUFFIX,
-          params: url_opts || {},
+          params: query_params,
           headers: DEFAULT_HEADERS_JSON,
-          body: body_hash,
-          body_json: body_json
+          body: nil,
+          body_json: nil
         )
       end
 

data/lib/search_engine/client/services/search.rb

@@ -21,8 +21,8 @@ module SearchEngine
 
           result = instrumented_search(collection, params_obj, cache_params, path, payload, start)
           duration = current_monotonic_ms - start
-          instrument(:post, path, duration, cache_params, request_token: start)
-          log_success(:post, path, start, cache_params)
+          instrument(:get, path, duration, cache_params, request_token: start)
+          log_success(:get, path, start, cache_params)
 
           klass = begin
             SearchEngine.collection_for(collection)
@@ -45,7 +45,7 @@ module SearchEngine
           bodies = Array(searches).map { |s| sanitize_body_params(s) }
 
           result = with_exception_mapping(:post, path, cache_params, start) do
-            typesense.multi_search.perform({ searches: bodies }, common_params: cache_params)
+            typesense.multi_search.perform({ searches: bodies }, cache_params)
           end
 
           instrument(:post, path, current_monotonic_ms - start, cache_params, request_token: start)
@@ -64,7 +64,7 @@ module SearchEngine
             result = nil
             SearchEngine::Instrumentation.instrument('search_engine.search', se_payload) do |ctx|
               ctx[:params_preview] = SearchEngine::Instrumentation.redact(params_obj.to_h)
-              result = with_exception_mapping(:post, path, cache_params, start) do
+              result = with_exception_mapping(:get, path, cache_params, start) do
                 docs = typesense.collections[collection].documents
                 documents_search(docs, payload, cache_params)
               end
@@ -80,7 +80,7 @@ module SearchEngine
             end
             result
           else
-            with_exception_mapping(:post, path, cache_params, start) do
+            with_exception_mapping(:get, path, cache_params, start) do
               docs = typesense.collections[collection].documents
               documents_search(docs, payload, cache_params)
             end
@@ -170,19 +170,7 @@ module SearchEngine
         end
 
         def documents_search(docs, payload, common_params)
-          if documents_search_supports_common_params?(docs)
-            docs.search(payload, common_params: common_params)
-          else
-            docs.search(payload)
-          end
-        end
-
-        def documents_search_supports_common_params?(docs)
-          m = docs.method(:search)
-          params = m.parameters
-          params.any? { |(kind, _)| %i[key keyreq keyrest].include?(kind) }
-        rescue StandardError
-          false
+          docs.search(payload.merge(common_params))
         end
       end
     end

data/lib/search_engine/config.rb

@@ -278,6 +278,8 @@ module SearchEngine
       attr_accessor :delivery_table_name
       # @return [String] database table used by host-managed drain slots
       attr_accessor :drain_slot_table_name
+      # @return [String, nil] optional checkpoint table for bounded delivery discovery
+      attr_accessor :materialization_cursor_table_name
       # @return [String] PostgreSQL notification channel for wakeups
       attr_accessor :channel
       # @return [String] queue name used by host app job dispatch
@@ -936,6 +938,7 @@ module SearchEngine
         table_name: postgres_outbox.table_name,
         delivery_table_name: postgres_outbox.delivery_table_name,
         drain_slot_table_name: postgres_outbox.drain_slot_table_name,
+        materialization_cursor_table_name: postgres_outbox.materialization_cursor_table_name,
         channel: postgres_outbox.channel,
         queue_name: postgres_outbox.queue_name,
         batch_size: postgres_outbox.batch_size,

data/lib/search_engine/indexer.rb

@@ -241,7 +241,7 @@ module SearchEngine
         client = SearchEngine.client
         payload = { q: '*', query_by: cfg.default_query_by, per_page: 0, filter_by: filter }
         params = SearchEngine::CompiledParams.new(payload)
-        res = client.search(collection: into, params: params, url_opts: {})
+        res = client.search(collection: into, params: params, url_opts: { use_cache: false })
         res&.found
       rescue StandardError
         nil

data/lib/search_engine/observability.rb

@@ -141,12 +141,21 @@ module SearchEngine
     # @param vq [String]
     # @return [String]
     def self.redact_vector_query(vq)
-      return vq unless vq.is_a?(String)
-      return vq if SearchEngine.config.observability.redact_vectors == false
+      return vq if vq.nil? || SearchEngine.config.observability.redact_vectors == false
+      return '[REDACTED]' unless vq.is_a?(String)
 
-      vq.gsub(/\[(-?\d+(?:\.\d+)?(?:\s*,\s*-?\d+(?:\.\d+?))*)\]/) do
-        dims = Regexp.last_match(1).split(',').size
-        "[<#{dims} dims>]"
+      vector_array = /\A([^:]+:\(\s*)\[([^\[\]]*)\](?=\s*[,)])/
+      return '[REDACTED]' unless vq.match?(vector_array)
+
+      vq.sub(vector_array) do
+        prefix = Regexp.last_match(1)
+        values = Regexp.last_match(2)
+        next "#{prefix}[]" if values.strip.empty?
+        next "#{prefix}[#{values}]" if values.match?(/\A<\d+ dims>\z/)
+
+        numbers = values.split(',', -1).map(&:strip)
+        numeric = numbers.all? { |number| number.match?(/\A[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?\z/) }
+        "#{prefix}#{numeric ? "[<#{numbers.size} dims>]" : '[REDACTED]'}"
       end
     end
 

data/lib/search_engine/postgres_outbox/materialization_cursor.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module SearchEngine
+  module PostgresOutbox
+    # Read under the outbox materialization lock. One page follows new event IDs;
+    # the other sweeps backwards to revisit late commits, due retries and existing events.
+    class MaterializationCursor
+      PAGE_SIZE = 1000
+
+      def initialize(connection, events_table, cursor_table, target_keys)
+        @connection = connection
+        @events = events_table
+        @table = connection.quote_table_name(cursor_table)
+        @scope = connection.quote(Digest::SHA256.hexdigest(JSON.generate([events_table, target_keys.uniq.sort])))
+      end
+
+      # @param limit [Integer] upper bound on the number of event IDs to read in each direction
+      # @return [Array<Integer>] event IDs to check against the configured delivery targets
+      def candidate_ids(limit:)
+        @page_size = [PAGE_SIZE, limit].min
+        state = @connection.select_all(<<~SQL).first
+          SELECT forward_id, backfill_through_id FROM #{@table} WHERE target_scope = #{@scope}
+        SQL
+        if state
+          @forward_id = Integer(state.fetch('forward_id'))
+          @backfill_through_id = Integer(state.fetch('backfill_through_id'))
+        else
+          @forward_id, @backfill_through_id = initialize_positions
+        end
+
+        # Recheck a recent ID range for concurrent inserts that commit behind the watermark.
+        # Even for dense IDs, at least half of the page remains available for new events.
+        @forward_page = event_ids("id > #{@forward_id - @page_size / 2} ORDER BY id ASC")
+        @backfill_page = event_ids("id <= #{@backfill_through_id} ORDER BY id DESC")
+        @forward_page | @backfill_page
+      end
+
+      # Save progress in the same transaction as the new deliveries.
+      def advance!
+        forward = [@forward_page.last || @forward_id, @forward_id].max
+        # Freeze the upper boundary until the backwards sweep reaches the beginning.
+        backfill = @backfill_page.size < @page_size ? forward : @backfill_page.last - 1
+        return if forward == @forward_id && backfill == @backfill_through_id
+
+        @connection.execute(<<~SQL)
+          UPDATE #{@table} SET forward_id = #{forward}, backfill_through_id = #{backfill}
+          WHERE target_scope = #{@scope}
+        SQL
+      end
+
+      private
+
+      def initialize_positions
+        head = Integer(@connection.select_value("SELECT COALESCE(MAX(id), 0) FROM #{@events}"))
+        @connection.execute(<<~SQL)
+          INSERT INTO #{@table} (target_scope, forward_id, backfill_through_id)
+          VALUES (#{@scope}, #{head}, #{head})
+        SQL
+        [head, head]
+      end
+
+      def event_ids(order)
+        @connection.select_all("SELECT id FROM #{@events} WHERE #{order} LIMIT #{@page_size}").map do |row|
+          Integer(row.fetch('id'))
+        end
+      end
+    end
+  end
+end

data/lib/search_engine/postgres_outbox/migration_helpers.rb

@@ -102,6 +102,15 @@ module SearchEngine
                         on_delete: :cascade
       end
 
+      # Create the small checkpoint table used for bounded delivery discovery.
+      # @param table_name [String, Symbol] table configured as materialization_cursor_table_name
+      def create_search_engine_outbox_materialization_cursors(table_name: :search_engine_outbox_materialization_cursors)
+        create_table table_name, id: :string, primary_key: :target_scope do |t|
+          t.bigint :forward_id, null: false
+          t.bigint :backfill_through_id, null: false
+        end
+      end
+
       # Create the SearchEngine outbox drain slots table.
       #
       # @param table_name [String, Symbol] destination drain slots table name

data/lib/search_engine/postgres_outbox/repository.rb

@@ -9,6 +9,7 @@ module SearchEngine
     class Repository
       # Keep expensive duplicate-key ranking bounded while leaving headroom for hot keys.
       CLAIM_CANDIDATE_OVERSAMPLE = 4
+      MATERIALIZATION_LOCK_NAMESPACE = 0x53454F42 # SEOB
       ERROR_LIMIT = 1000
       PROCESSED_AT_ASSIGNMENT = 'processed_at = CURRENT_TIMESTAMP'
       RETIREMENT_BATCH_SIZE = 1000
@@ -181,43 +182,27 @@ module SearchEngine
         with_delivery_target_session_lock(target, mode: :shared, timing: timing, &block)
       end
 
-      # Create missing delivery rows for all configured delivery targets.
-      # @return [void]
+      # Create missing deliveries. Concurrent pollers leave discovery to the current owner.
+      # @return [Array<Hash>, nil] materialized events, or nil when no targets are configured
       def materialize_deliveries!(limit: nil)
         targets = materialization_delivery_targets
         return if targets.empty?
 
-        # Discover work without row locks, then acquire every affected parent before any delivery.
-        # The exact preview is revalidated under those parent locks before mutations begin.
-        preview_rows = select_rows(delivery_materialization_select_sql(limit, targets, lock: false))
-        return preview_rows if preview_rows.empty?
+        scan_limit = collection_limited_batch?(limit) ? collection_limited_candidate_limit : global_limit_for(limit)
+        return [] if scan_limit.zero?
 
-        supersede_parents = select_rows(supersede_parent_ids_sql(preview_rows))
-        rows = []
         connection.transaction do
-          parent_ids = preview_rows.map { |row| row_value(row, :id) }
-          parent_ids.concat(supersede_parents.map { |row| row_value(row, :event_id) })
-          lock_event_rows!(parent_ids)
-
-          rows = select_rows(
-            delivery_materialization_select_sql(
-              limit,
-              targets,
-              event_ids: preview_rows.map { |row| row_value(row, :id) }
-            )
-          )
-          next if rows.empty?
-
-          supersede_candidates = select_rows(materialization_supersede_parent_candidates_sql(rows, targets))
-          older_event_ids = supersede_candidates.map { |candidate| row_value(candidate, :event_id) }
-          older_delivery_ids = supersede_candidates.map { |candidate| row_value(candidate, :delivery_id) }
-          lock_delivery_rows!(older_delivery_ids)
-          supersede_pending_events_by_id!(older_event_ids)
-          supersede_pending_deliveries!(older_delivery_ids, event_ids: older_event_ids)
-          execute(delivery_materialization_insert_sql(rows, targets))
+          next [] unless materialization_lock_acquired?
+
+          cursor = materialization_cursor(targets)
+          event_ids = cursor&.candidate_ids(limit: scan_limit)
+          preview = select_rows(delivery_materialization_select_sql(limit, targets, event_ids: event_ids, lock: false))
+          rows = preview.empty? ? [] : materialize_batch(limit, targets, preview)
+          if cursor && rows.size == preview.size && materialization_page_drained?(rows, event_ids, limit)
+            cursor.advance!
+          end
+          rows
         end
-
-        rows
       end
 
       # Refresh cleanup-eligible parent event statuses from terminal delivery rows.
@@ -415,6 +400,49 @@ module SearchEngine
         end
       end
 
+      # PostgreSQL's two-integer lock space is separate from the single-key delivery cutover locks.
+      def materialization_lock_acquired?
+        sql = <<~SQL
+          SELECT pg_try_advisory_xact_lock(#{MATERIALIZATION_LOCK_NAMESPACE}, #{quote(quoted_table)}::regclass::integer)
+        SQL
+        advisory_lock_truthy?(select_scalar(sql))
+      end
+
+      def materialization_cursor(targets)
+        table = SearchEngine.config.postgres_outbox.materialization_cursor_table_name
+        MaterializationCursor.new(connection, quoted_table, table, targets.map(&:key)) if table
+      end
+
+      # When a quota may have omitted matches, revisit the page after these deliveries commit.
+      def materialization_page_drained?(rows, event_ids, limit)
+        return true if rows.empty? || rows.size == event_ids.size
+
+        batch_size = global_limit_for(limit)
+        return rows.size < batch_size unless collection_limited_batch?(limit)
+
+        per_collection = SearchEngine.config.postgres_outbox.normalized_batch_sizes.values
+        rows.size < [batch_size, *per_collection].min
+      end
+
+      # Revalidate the exact preview under parent locks before locking any deliveries.
+      def materialize_batch(limit, targets, preview_rows)
+        supersede_parents = select_rows(supersede_parent_ids_sql(preview_rows))
+        preview_ids = preview_rows.map { |row| row_value(row, :id) }
+        lock_event_rows!(preview_ids + supersede_parents.map { |row| row_value(row, :event_id) })
+
+        rows = select_rows(delivery_materialization_select_sql(limit, targets, event_ids: preview_ids))
+        return rows if rows.empty?
+
+        supersede_candidates = select_rows(materialization_supersede_parent_candidates_sql(rows, targets))
+        older_event_ids = supersede_candidates.map { |candidate| row_value(candidate, :event_id) }
+        older_delivery_ids = supersede_candidates.map { |candidate| row_value(candidate, :delivery_id) }
+        lock_delivery_rows!(older_delivery_ids)
+        supersede_pending_events_by_id!(older_event_ids)
+        supersede_pending_deliveries!(older_delivery_ids, event_ids: older_event_ids)
+        execute(delivery_materialization_insert_sql(rows, targets))
+        rows
+      end
+
       def claim_pending_deliveries(limit:, worker_id:)
         rows = claim_pending_delivery_rows(limit: limit, worker_id: worker_id)
 
@@ -431,51 +459,34 @@ module SearchEngine
           return collection_limited_materialization_select_sql(targets, event_ids: event_ids, lock: lock)
         end
 
-        limit = global_limit_for(limit)
         <<~SQL
-          WITH target(target_key, queue_name) AS (
-            VALUES #{delivery_target_values_sql(targets)}
-          ),
-          candidate_events AS MATERIALIZED (
-            SELECT outbox.id,
-                   outbox.collection,
-                   outbox.document_id
-            FROM #{quoted_table} outbox
-            WHERE outbox.status IN ('pending', 'processing', 'failed')
-              AND (outbox.next_attempt_at IS NULL OR outbox.next_attempt_at <= CURRENT_TIMESTAMP)
-              #{newer_event_exclusion_sql('outbox')}
-              #{event_id_filter_sql('outbox', event_ids)}
-              AND EXISTS (
-                SELECT 1
-                FROM target
-                WHERE NOT EXISTS (
-                  SELECT 1
-                  FROM #{quoted_delivery_table} deliveries
-                  WHERE deliveries.event_id = outbox.id
-                    AND deliveries.target_key = target.target_key
-                )
-              )
-            ORDER BY outbox.id ASC
-            LIMIT #{limit}
-            #{row_lock_sql(lock)}
-          ),
-          latest_candidate_ids AS (
-            SELECT id
-            FROM (
-              SELECT id,
-                     ROW_NUMBER() OVER (
-                       PARTITION BY collection, document_id
-                       ORDER BY id DESC
-                     ) AS row_number
-              FROM candidate_events
-            ) ranked_candidate_events
-            WHERE row_number = 1
-          )
-          SELECT outbox.*
+          SELECT #{lock ? 'outbox.*' : 'outbox.id, outbox.collection, outbox.document_id'}
           FROM #{quoted_table} outbox
-          INNER JOIN latest_candidate_ids
-            ON latest_candidate_ids.id = outbox.id
+          WHERE #{materialization_filter_sql(targets, event_ids)}
           ORDER BY outbox.id ASC
+          LIMIT #{global_limit_for(limit)}
+          #{row_lock_sql(lock)}
+        SQL
+      end
+
+      # Each membership check reads at most one unique delivery per requested key.
+      # The scalar newer-event probe also prevents a hash over the entire parent history.
+      def materialization_filter_sql(targets, event_ids)
+        keys = targets.map(&:key).uniq
+        <<~SQL.chomp
+          outbox.status IN ('pending', 'processing', 'failed')
+          AND (outbox.next_attempt_at IS NULL OR outbox.next_attempt_at <= CURRENT_TIMESTAMP)
+          #{event_id_filter_sql('outbox', event_ids)}
+          AND (
+            SELECT newer.id FROM #{quoted_table} newer
+            WHERE newer.collection = outbox.collection AND newer.document_id = outbox.document_id
+              AND newer.id > outbox.id
+            LIMIT 1
+          ) IS NULL
+          AND (
+            SELECT COUNT(*) FROM #{quoted_delivery_table} deliveries
+            WHERE deliveries.event_id = outbox.id AND deliveries.target_key IN (#{ids_sql(keys)})
+          ) < #{keys.size}
         SQL
       end
 
@@ -683,6 +694,8 @@ module SearchEngine
       end
 
       def select_scalar(sql)
+        # Advisory locks and quiescence polls must reach the current database session on every attempt.
+        return connection.exec_query(sql).rows.first&.first if connection.respond_to?(:exec_query)
         return connection.select_value(sql) if connection.respond_to?(:select_value)
 
         result = connection.execute(sql)
@@ -1594,64 +1607,32 @@ module SearchEngine
 
       def collection_limited_materialization_select_sql(targets, event_ids: nil, lock: true)
         <<~SQL
-          WITH target(target_key, queue_name) AS (
-            VALUES #{delivery_target_values_sql(targets)}
-          ),
-          #{collection_limits_cte_sql},
+          WITH #{collection_limits_cte_sql},
           candidate_events AS MATERIALIZED (
-            SELECT outbox.id,
-                   outbox.collection,
-                   outbox.document_id
+            SELECT outbox.id, outbox.collection
             FROM #{quoted_table} outbox
-            WHERE outbox.status IN ('pending', 'processing', 'failed')
-              AND (outbox.next_attempt_at IS NULL OR outbox.next_attempt_at <= CURRENT_TIMESTAMP)
-              #{newer_event_exclusion_sql('outbox')}
-              #{event_id_filter_sql('outbox', event_ids)}
-              AND EXISTS (
-                SELECT 1
-                FROM target
-                WHERE NOT EXISTS (
-                  SELECT 1
-                  FROM #{quoted_delivery_table} deliveries
-                  WHERE deliveries.event_id = outbox.id
-                    AND deliveries.target_key = target.target_key
-                )
-            )
+            WHERE #{materialization_filter_sql(targets, event_ids)}
             ORDER BY outbox.id ASC
             LIMIT #{collection_limited_candidate_limit}
             #{row_lock_sql(lock)}
           ),
-          latest_candidate_ids AS (
-            SELECT id,
-                   collection
-            FROM (
-              SELECT id,
-                     collection,
-                     ROW_NUMBER() OVER (
-                       PARTITION BY collection, document_id
-                       ORDER BY id DESC
-                     ) AS row_number
-              FROM candidate_events
-            ) ranked_candidate_events
-            WHERE row_number = 1
-          ),
           ranked_by_collection AS (
-            SELECT latest_candidate_ids.id,
+            SELECT candidate_events.id,
                    ROW_NUMBER() OVER (
-                     PARTITION BY latest_candidate_ids.collection
-                     ORDER BY latest_candidate_ids.id ASC
+                     PARTITION BY candidate_events.collection
+                     ORDER BY candidate_events.id ASC
                    ) AS collection_row_number,
                    COALESCE(collection_limits.batch_size, #{global_limit_for(nil)}) AS collection_batch_size
-            FROM latest_candidate_ids
+            FROM candidate_events
             LEFT JOIN collection_limits
-              ON collection_limits.collection = latest_candidate_ids.collection
+              ON collection_limits.collection = candidate_events.collection
           ),
           selected_candidate_ids AS (
             SELECT id
             FROM ranked_by_collection
             WHERE collection_row_number <= collection_batch_size
           )
-          SELECT outbox.*
+          SELECT #{lock ? 'outbox.*' : 'outbox.id, outbox.collection, outbox.document_id'}
           FROM #{quoted_table} outbox
           INNER JOIN selected_candidate_ids
             ON selected_candidate_ids.id = outbox.id
@@ -1784,18 +1765,6 @@ module SearchEngine
         Array(ids).compact.uniq(&:to_s)
       end
 
-      def newer_event_exclusion_sql(event_relation)
-        <<~SQL.chomp
-          AND NOT EXISTS (
-            SELECT 1
-            FROM #{quoted_table} newer_events
-            WHERE newer_events.collection = #{event_relation}.collection
-              AND newer_events.document_id = #{event_relation}.document_id
-              AND newer_events.id > #{event_relation}.id
-          )
-        SQL
-      end
-
       def processing_event_exclusion_sql(event_relation)
         <<~SQL.chomp
           AND NOT EXISTS (

data/lib/search_engine/postgres_outbox.rb

@@ -3,6 +3,7 @@
 require 'search_engine/postgres_outbox/event'
 require 'search_engine/postgres_outbox/delivery_target'
 require 'search_engine/postgres_outbox/processor_result'
+require 'search_engine/postgres_outbox/materialization_cursor'
 require 'search_engine/postgres_outbox/repository'
 require 'search_engine/postgres_outbox/event_processor'
 require 'search_engine/postgres_outbox/drainer'

data/lib/search_engine/relation/compiler.rb

@@ -518,7 +518,6 @@ module SearchEngine
 
         auto_include_embedding_in_query_by!(params, vq, field)
         auto_exclude_embedding_from_response!(params, field)
-        resolve_vector_distance_sort!(params, field)
         instrument_vector_compile(vq, params, field)
       end
 
@@ -538,7 +537,10 @@ module SearchEngine
           parts << "#{key}:#{vq[key]}" if vq.key?(key)
         end
         parts << "alpha:#{vq[:alpha]}" if vq.key?(:alpha) && hybrid_vector_mode?(params, vq)
-        parts << "queries:[#{vq[:queries].join(', ')}]" if vq[:queries]
+        if vq[:queries]
+          queries = vq[:queries].map { |query| "`#{query}`" }
+          parts << "queries:[#{queries.join(', ')}]"
+        end
         parts << "query_weights:[#{vq[:weights].join(', ')}]" if vq[:weights]
 
         inner = [vector_part, *parts].join(', ')
@@ -547,9 +549,10 @@ module SearchEngine
 
       # Hybrid mode: auto-append the embedding field to `query_by` so that
       # Typesense performs rank-fusion between keyword and vector results.
-      # Hybrid = text query present AND no explicit embedding vector supplied.
+      # Explicit vectors already supply the embedding and need no query_by addition.
       def auto_include_embedding_in_query_by!(params, vq, field)
         return unless hybrid_vector_mode?(params, vq)
+        return if vq.key?(:query)
 
         current = params[:query_by].to_s
         fields = current.split(',').map(&:strip)
@@ -571,19 +574,8 @@ module SearchEngine
         params[:exclude_fields] = current.empty? ? field : "#{current},#{field}"
       end
 
-      # Replace the `_vector_distance` sentinel produced by order normalization
-      # with the real Typesense sort token that references the embedding field.
-      def resolve_vector_distance_sort!(params, vq_field)
-        sort = params[:sort_by]
-        return unless sort&.include?(VECTOR_DISTANCE_SENTINEL)
-
-        params[:sort_by] = sort.gsub(/#{VECTOR_DISTANCE_SENTINEL}:(asc|desc)/) do
-          "_vector_query(#{vq_field}:([])):#{Regexp.last_match(1)}"
-        end
-      end
-
       def hybrid_vector_mode?(params, vq)
-        params[:q].to_s != '*' && !vq.key?(:query) && !vq.key?(:id) && !vq.key?(:queries)
+        params[:q].to_s != '*' && !vq.key?(:id) && !vq.key?(:queries)
       end
 
       def explicitly_selected_field?(field_name)

data/lib/search_engine/relation/dsl/vectors.rb

@@ -63,6 +63,9 @@ module SearchEngine
 
           validate_vector_query_mode_exclusivity!(query, id, queries)
           validate_vector_query_array!(query)
+          validate_vector_dimensions!(field_sym, query) if query
+          normalized_id = id.to_s unless id.nil?
+          validate_vector_id!(normalized_id)
           validate_vector_queries!(queries)
           validate_vector_weights!(weights, queries)
 
@@ -75,11 +78,11 @@ module SearchEngine
           result = { field: field_sym }
           result[:k] = coerced_k if coerced_k
           result[:alpha] = Float(alpha) if alpha
-          result[:query] = query if query
-          result[:id] = id.to_s if id
+          result[:query] = query.map(&:to_f) if query
+          result[:id] = normalized_id.dup unless normalized_id.nil?
           result[:distance_threshold] = Float(distance_threshold) if distance_threshold
-          result[:queries] = queries if queries
-          result[:weights] = weights if weights
+          result[:queries] = queries.map(&:dup) if queries
+          result[:weights] = weights.map(&:to_f) if weights
           result[:ef] = coerced_ef if coerced_ef
           result[:flat_search_cutoff] = coerced_flat if coerced_flat
           result
@@ -106,11 +109,19 @@ module SearchEngine
 
           sym = field.to_sym
           attrs = safe_attributes_map
-          return if attrs.nil? || attrs.empty?
+          return if attrs.nil?
 
           embeddings = vector_embeddings_map
 
-          return if attrs.key?(sym) || embeddings.key?(sym)
+          return if embeddings.key?(sym) || [:vector, [:float], :'float[]', 'float[]'].include?(attrs[sym])
+
+          if attrs.key?(sym)
+            raise SearchEngine::Errors::InvalidVectorQuery.new(
+              "InvalidVectorQuery: field :#{sym} must be a vector or float array",
+              doc: VECTOR_SEARCH_DOC_URL,
+              details: { field: sym, type: attrs[sym] }
+            )
+          end
 
           known = (attrs.keys + embeddings.keys).uniq
           suggestions = suggest_fields(sym, known)
@@ -128,9 +139,9 @@ module SearchEngine
 
         def validate_vector_query_mode_exclusivity!(query, id, queries)
           modes = []
-          modes << :query if query
-          modes << :id if id
-          modes << :queries if queries
+          modes << :query unless query.nil?
+          modes << :id unless id.nil?
+          modes << :queries unless queries.nil?
           return if modes.length <= 1
 
           raise SearchEngine::Errors::InvalidVectorQuery.new(
@@ -146,9 +157,9 @@ module SearchEngine
         def validate_vector_query_array!(query)
           return if query.nil?
 
-          unless query.is_a?(Array) && query.all? { |v| v.is_a?(Numeric) }
+          unless query.is_a?(Array) && query.all? { |v| finite_vector_number?(v) }
             raise SearchEngine::Errors::InvalidVectorQuery.new(
-              'InvalidVectorQuery: query: must be an Array of Numeric values',
+              'InvalidVectorQuery: query: must be an Array of finite real numbers',
               hint: 'Pass a float array like [0.1, 0.2, ...]',
               doc: VECTOR_SEARCH_DOC_URL,
               details: { query_class: query.class.name }
@@ -164,6 +175,35 @@ module SearchEngine
           )
         end
 
+        def finite_vector_number?(value)
+          value.is_a?(Numeric) && value.real? && value.to_f.finite?
+        end
+
+        def validate_vector_dimensions!(field, query)
+          metadata = vector_embeddings_map[field] || {}
+          options = @klass.respond_to?(:attribute_options) ? @klass.attribute_options[field] || {} : {}
+          dimension = metadata[:num_dim] || options[:num_dim]
+          return if dimension.nil? || query.size == Integer(dimension)
+
+          raise SearchEngine::Errors::InvalidVectorQuery.new(
+            "InvalidVectorQuery: field :#{field} expects #{dimension} dimensions (got #{query.size})",
+            doc: VECTOR_SEARCH_DOC_URL,
+            details: { field: field, expected: dimension, actual: query.size }
+          )
+        end
+
+        def validate_vector_id!(id)
+          return if id.nil?
+
+          value = id.to_s
+          return if !value.empty? && value == value.strip && !value.match?(/[:,()[:cntrl:]]/)
+
+          raise SearchEngine::Errors::InvalidVectorQuery.new(
+            'InvalidVectorQuery: id: cannot be blank or contain vector-query delimiters or surrounding whitespace',
+            doc: VECTOR_SEARCH_DOC_URL
+          )
+        end
+
         def validate_vector_queries!(queries)
           return if queries.nil?
 
@@ -183,6 +223,14 @@ module SearchEngine
             )
           end
 
+          if queries.any? { |query| query != query.strip || query.match?(/[:`[:cntrl:]]/) }
+            raise SearchEngine::Errors::InvalidVectorQuery.new(
+              'InvalidVectorQuery: queries: cannot contain unsupported delimiters or surrounding whitespace',
+              hint: 'Colons, backticks and control characters cannot be represented in historical queries',
+              doc: VECTOR_SEARCH_DOC_URL
+            )
+          end
+
           blank_indices = queries.each_index.select { |i| queries[i].strip.empty? }
           return if blank_indices.empty?
 
@@ -197,9 +245,9 @@ module SearchEngine
         def validate_vector_weights!(weights, queries)
           return if weights.nil?
 
-          unless weights.is_a?(Array) && weights.all? { |v| v.is_a?(Numeric) }
+          unless weights.is_a?(Array) && weights.all? { |v| finite_vector_number?(v) }
             raise SearchEngine::Errors::InvalidVectorQuery.new(
-              'InvalidVectorQuery: weights: must be an Array of Numeric',
+              'InvalidVectorQuery: weights: must be an Array of finite real numbers',
               doc: VECTOR_SEARCH_DOC_URL,
               details: { weights_class: weights.class.name }
             )
@@ -221,7 +269,7 @@ module SearchEngine
             )
           end
 
-          sum = weights.sum.to_f
+          sum = weights.sum(&:to_f)
           tolerance = SearchEngine.config.embedding.weights_sum_tolerance
           return if (sum - 1.0).abs <= tolerance
 
@@ -239,7 +287,7 @@ module SearchEngine
 
           begin
             fv = Float(alpha)
-          rescue ArgumentError, TypeError
+          rescue ArgumentError, TypeError, RangeError
             raise SearchEngine::Errors::InvalidVectorQuery.new(
               "InvalidVectorQuery: alpha: must be a Numeric between 0.0 and 1.0 (got #{alpha.inspect})",
               doc: VECTOR_SEARCH_DOC_URL,
@@ -262,7 +310,7 @@ module SearchEngine
 
           begin
             fv = Float(distance_threshold)
-          rescue ArgumentError, TypeError
+          rescue ArgumentError, TypeError, RangeError
             raise SearchEngine::Errors::InvalidVectorQuery.new(
               'InvalidVectorQuery: distance_threshold: must be a non-negative Numeric ' \
               "(got #{distance_threshold.inspect})",
@@ -285,7 +333,7 @@ module SearchEngine
 
           begin
             iv = Integer(value)
-          rescue ArgumentError, TypeError
+          rescue ArgumentError, TypeError, RangeError
             raise SearchEngine::Errors::InvalidVectorQuery.new(
               "InvalidVectorQuery: #{name}: must be a positive Integer (got #{value.inspect})",
               doc: VECTOR_SEARCH_DOC_URL,
@@ -293,10 +341,10 @@ module SearchEngine
             )
           end
 
-          return iv if iv.positive?
+          return iv if iv.positive? && (value.is_a?(String) || value == iv)
 
           raise SearchEngine::Errors::InvalidVectorQuery.new(
-            "InvalidVectorQuery: #{name}: must be > 0 (got #{iv})",
+            "InvalidVectorQuery: #{name}: must be a positive Integer without truncation",
             doc: VECTOR_SEARCH_DOC_URL,
             details: { name => iv }
           )
@@ -342,8 +390,6 @@ module SearchEngine
           return {} unless @klass.respond_to?(:embeddings_config)
 
           @klass.embeddings_config || {}
-        rescue StandardError
-          {}
         end
 
         def build_vector_field_suggestion(suggestions)

data/lib/search_engine/relation/dsl.rb

@@ -548,8 +548,7 @@ module SearchEngine
       ORDER_ALIASES = { 'text_match' => '_text_match', 'vector_distance' => '_vector_distance' }.freeze
 
       # Map DSL sort aliases to Typesense internal tokens.
-      # `_vector_distance` is a sentinel resolved by the compiler once the
-      # embedding field name is known.
+      # `_vector_distance` sorts the active vector query without re-embedding it.
       def resolve_order_alias(field)
         ORDER_ALIASES.fetch(field, field)
       end

data/lib/search_engine/relation/dx/dry_run.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'shellwords'
 
 module SearchEngine
   class Relation
@@ -36,13 +37,17 @@ module SearchEngine
           end
         end
 
-        # Build a single-line curl string with redacted body.
+        # Build a shell-quoted GET search command with redacted URL parameters.
         # @param url [String]
         # @param params [Hash]
+        # @param url_opts [Hash] request-level cache controls
         # @return [String]
-        def self.curl(url, params)
-          body_json = JSON.generate(redact_params(params))
-          %(curl -X POST #{url} -H 'Content-Type: application/json' -H 'X-TYPESENSE-API-KEY: ***' -d '#{body_json}')
+        def self.curl(url, params, url_opts: {})
+          query = redact_params(params).reject { |key, _value| key == :_hits }
+          query.merge!(SearchEngine::Observability.filtered_url_opts(url_opts))
+          arguments = ['curl', '--get', url, '-H', 'X-TYPESENSE-API-KEY: ***']
+          query.each { |key, value| arguments.concat(['--data-urlencode', "#{key}=#{value}"]) }
+          Shellwords.join(arguments)
         end
 
         # Return a structured dry-run payload with redacted JSON body and url options.

data/lib/search_engine/relation/dx.rb

@@ -11,7 +11,7 @@ module SearchEngine
     # DX helpers are mixed into `Relation` to offer redaction‑aware, zero‑I/O explain and preview utilities.
     # These helpers are pure and never mutate relation state.
     module Dx
-      # Return the request body JSON after compile, fully redacted.
+      # Return the compiled search parameters as fully redacted JSON.
       # @param pretty [Boolean] pretty-print with stable key ordering when true
       # @return [String]
       # @since M8
@@ -22,14 +22,14 @@ module SearchEngine
         SearchEngine::Relation::Dx::DryRun.to_json(redacted, pretty: pretty)
       end
 
-      # Return a single-line curl command with redacted API key and JSON body.
+      # Return a shell-quoted GET curl command with redacted API key and parameters.
       # @return [String]
       # @since M8
       # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/dx
       def to_curl
         url = compiled_url
         params = SearchEngine::CompiledParams.from(to_typesense_params).to_h
-        SearchEngine::Relation::Dx::DryRun.curl(url, params)
+        SearchEngine::Relation::Dx::DryRun.curl(url, params, url_opts: compiled_url_opts)
       end
 
       # Compile and validate without performing network I/O.

data/lib/search_engine/result.rb

@@ -96,6 +96,7 @@ module SearchEngine
           attach_curation!(obj, entry)
           attach_highlighting!(obj, entry)
           attach_geo_distance!(obj, entry)
+          attach_vector_distance!(obj, entry)
           hydrated << obj
         end
         @hits = hydrated.freeze
@@ -296,6 +297,14 @@ module SearchEngine
       end
     end
 
+    # Backend vector distance metadata, distinct from document attributes.
+    module VectorDistance
+      # @return [Numeric, nil] the unmodified distance supplied by Typesense
+      def vector_distance
+        instance_variable_get(:@__se_vector_distance__)
+      end
+    end
+
     # Per-hit curation mixin: added onto hydrated objects when Typesense
     # returns curated metadata for the hit.
     module HitCuration
@@ -414,6 +423,7 @@ module SearchEngine
           attach_curation!(obj, sym_sub)
           attach_highlighting!(obj, sym_sub)
           attach_geo_distance!(obj, sym_sub)
+          attach_vector_distance!(obj, sym_sub)
           hydrated << obj
         end
 
@@ -569,6 +579,14 @@ module SearchEngine
       obj
     end
 
+    def attach_vector_distance!(obj, hit_entry)
+      return obj unless hit_entry.key?(:vector_distance)
+
+      obj.singleton_class.prepend(VectorDistance)
+      obj.instance_variable_set(:@__se_vector_distance__, hit_entry[:vector_distance])
+      obj
+    end
+
     def attach_geo_distance!(obj, hit_entry)
       raw_geo = hit_entry[:geo_distance_meters]
       return obj unless raw_geo.is_a?(Hash) && !raw_geo.empty?

data/lib/search_engine/version.rb

@@ -3,5 +3,5 @@
 module SearchEngine
   # Current gem version.
   # @return [String]
-  VERSION = '30.8.24'
+  VERSION = '30.9.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: search-engine-for-typesense
 version: !ruby/object:Gem::Version
-  version: 30.8.24
+  version: 30.9.1
 platform: ruby
 authors:
 - Nikita Shkoda
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -189,6 +189,7 @@ files:
 - lib/search_engine/postgres_outbox/event.rb
 - lib/search_engine/postgres_outbox/event_processor.rb
 - lib/search_engine/postgres_outbox/listener.rb
+- lib/search_engine/postgres_outbox/materialization_cursor.rb
 - lib/search_engine/postgres_outbox/migration_helpers.rb
 - lib/search_engine/postgres_outbox/processor_result.rb
 - lib/search_engine/postgres_outbox/repository.rb