search-engine-for-typesense 30.9.1 → 30.9.3

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

@@ -17,25 +17,7 @@ module SearchEngine
           # @param args [Array<Object>]
           # @return [SearchEngine::Relation]
           def not(*args)
-            @relation.send(:validate_not_args!, args)
-            nodes = Array(@relation.send(:build_ast_with_empty_array_rewrites, args, negated: true))
-
-            # Invert non-hidden predicates (Eq, In) returned by the builder
-            negated = nodes.map do |node|
-              case node
-              when SearchEngine::AST::Eq
-                SearchEngine::AST.not_eq(node.field, node.value)
-              when SearchEngine::AST::In
-                SearchEngine::AST.not_in(node.field, node.values)
-              else
-                node
-              end
-            end
-
-            @relation.send(:spawn) do |s|
-              s[:ast] = Array(s[:ast]) + negated
-              s[:filters] = Array(s[:filters])
-            end
+            @relation.not(*args)
           end
         end
 
@@ -47,11 +29,9 @@ module SearchEngine
           return self if args.nil? || args.empty?
           return self if blank_where_args?(args)
 
-          ast_nodes = build_ast_with_empty_array_rewrites(args, negated: false)
-          fragments = normalize_where(args)
+          ast_nodes = build_filter_nodes(args, negated: false)
           spawn do |s|
             s[:ast] = Array(s[:ast]) + Array(ast_nodes)
-            s[:filters] = Array(s[:filters]) + fragments
           end
         end
 
@@ -61,23 +41,10 @@ module SearchEngine
         # @return [SearchEngine::Relation]
         def not(*args)
           validate_not_args!(args)
-          nodes = Array(build_ast_with_empty_array_rewrites(args, negated: true))
-
-          negated = nodes.map do |node|
-            case node
-            when SearchEngine::AST::Eq
-              SearchEngine::AST.not_eq(node.field, node.value)
-            when SearchEngine::AST::In
-              SearchEngine::AST.not_in(node.field, node.values)
-            else
-              node
-            end
-          end
+          nodes = build_filter_nodes(args, negated: true)
+          raise SearchEngine::Errors::InvalidOperator, 'where.not requires a predicate' if nodes.empty?
 
-          spawn do |s|
-            s[:ast] = Array(s[:ast]) + negated
-            s[:filters] = Array(s[:filters])
-          end
+          spawn { |state| state[:ast] = Array(state[:ast]) + nodes }
         end
 
         # Replace all predicates with a new where input.
@@ -249,93 +216,77 @@ module SearchEngine
           end
         end
 
-        # Build AST nodes, rewriting:
-        # - empty-array predicates to hidden *_empty flags when enabled (existing behavior)
-        # - nil predicates to hidden *_blank flags when `optional` is enabled (new behavior)
-        # Delegates other inputs to the DSL parser.
-        def build_ast_with_empty_array_rewrites(args, negated: false)
-          # Preserve input shape so template bind arrays stay intact:
-          # where('field IN ?', [1, 2]) => ['field IN ?', [1, 2]]
-          items = Array(args).compact
-          return [] if items.empty?
-
-          out_nodes = []
-          non_hash_items = []
-
-          items.each do |entry|
+        def build_filter_nodes(args, negated:)
+          nodes = []
+          expressions = []
+          args.each do |entry|
             if entry.is_a?(Hash)
-              process_hash_entry(entry, out_nodes, negated)
+              entry.each do |field, value|
+                if join_scope_value?(value) && join_assoc?(field)
+                  scoped = []
+                  process_join_scope(field, value, scoped)
+                  nodes.concat(negated ? scoped.map { |node| invert_predicate(node) } : scoped)
+                elsif value.is_a?(Hash)
+                  SearchEngine::DSL::Parser.validate_assoc_and_join!(@klass, field.to_sym, joins_list)
+                  value.each do |inner_field, inner_value|
+                    nodes << hash_predicate(inner_field, inner_value, assoc: field, negated: negated)
+                  end
+                else
+                  nodes << hash_predicate(field, value, negated: negated)
+                end
+              end
             else
-              non_hash_items << entry
+              expressions << entry
             end
           end
 
-          unless non_hash_items.empty?
-            out_nodes.concat(
-              Array(SearchEngine::DSL::Parser.parse_list(non_hash_items, klass: @klass, joins: joins_list))
-            )
+          parsed = SearchEngine::DSL::Parser.parse_list(expressions, klass: @klass, joins: joins_list)
+          nodes.concat(negated ? parsed.map { |node| invert_predicate(node) } : parsed)
+        end
+
+        def hash_predicate(key, value, negated:, assoc: nil)
+          field = SearchEngine::Filters::Sanitizer.field_name(key).to_sym
+          empty_array = value.is_a?(Array) && value.flatten(1).compact.empty?
+          if value.nil? || empty_array
+            lhs = assoc ? "$#{assoc}.#{field}" : field.to_s
+            empty = assoc ? joined_empty_filtering_enabled?(assoc, field) : base_empty_filtering_enabled?(field)
+            blank = assoc ? joined_optional_enabled?(assoc, field) : base_optional_enabled?(field)
+            raise_empty_array_type!(field) if empty_array && !empty
+
+            flags = []
+            flags << SearchEngine::AST.eq("#{lhs}_empty", !negated) if empty
+            flags << SearchEngine::AST.eq("#{lhs}_blank", !negated) if blank && value.nil?
+            return flags.first if flags.size == 1
+            if flags.size > 1
+              return SearchEngine::AST.group(negated ? SearchEngine::AST.and_(*flags) : SearchEngine::AST.or_(*flags))
+            end
           end
 
-          out_nodes.flatten.compact
+          predicate = { field => value }
+          predicate = { assoc => predicate } if assoc
+          node = SearchEngine::DSL::Parser.parse(predicate, klass: @klass, joins: joins_list)
+          negated ? invert_predicate(node) : node
         end
 
-        def process_hash_entry(entry, out_nodes, negated)
-          entry.each do |k, v|
-            # Join-scope shorthand: where(assoc: :scope) or where(assoc: [:s1, :s2])
-            if join_scope_value?(v) && join_assoc?(k)
-              process_join_scope(k.to_sym, v, out_nodes)
-            elsif v.is_a?(Hash)
-              process_join_predicate(k, v, out_nodes, negated)
-            else
-              process_base_predicate(k, v, out_nodes, negated)
-            end
-          end
-        end
+        INVERSE_PREDICATES = {
+          eq: :not_eq, not_eq: :eq, in: :not_in, not_in: :in_,
+          gt: :lte, gte: :lt, lt: :gte, lte: :gt
+        }.freeze
+        private_constant :INVERSE_PREDICATES
 
-        def process_join_predicate(assoc_key, values_hash, out_nodes, negated)
-          assoc = assoc_key.to_sym
-          values_hash.each do |inner_field, inner_value|
-            field_sym = inner_field.to_sym
-            if inner_value.nil?
-              emit_nil_flags_for_join(out_nodes, assoc, field_sym, negated)
-            elsif array_like?(inner_value)
-              arr = Array(inner_value).flatten(1).compact
-              if arr.empty?
-                if joined_empty_filtering_enabled?(assoc, field_sym)
-                  emit_empty_array_flag(out_nodes, "$#{assoc}.#{field_sym}_empty", negated)
-                else
-                  raise_empty_array_type!(field_sym)
-                end
-              else
-                out_nodes << SearchEngine::DSL::Parser.parse(
-                  { assoc => { field_sym => inner_value } }, klass: @klass, joins: joins_list
-                )
-              end
-            else
-              out_nodes << SearchEngine::DSL::Parser.parse(
-                { assoc => { field_sym => inner_value } }, klass: @klass, joins: joins_list
-              )
-            end
-          end
-        end
+        def invert_predicate(node)
+          inverse = INVERSE_PREDICATES[node.type]
+          return SearchEngine::AST.public_send(inverse, node.field, node.right) if inverse
 
-        def process_base_predicate(field_key, value, out_nodes, negated)
-          field = field_key.to_sym
-          if value.nil?
-            emit_nil_flags_for_base(out_nodes, field, negated)
-          elsif array_like?(value)
-            arr = Array(value).flatten(1).compact
-            if arr.empty?
-              if base_empty_filtering_enabled?(field)
-                emit_empty_array_flag(out_nodes, "#{field}_empty", negated)
-              else
-                raise_empty_array_type!(field)
-              end
-            else
-              out_nodes << SearchEngine::DSL::Parser.parse({ field => value }, klass: @klass, joins: joins_list)
-            end
+          case node
+          when SearchEngine::AST::And
+            SearchEngine::AST.or_(*node.children.map { |child| invert_predicate(child) })
+          when SearchEngine::AST::Or
+            SearchEngine::AST.and_(*node.children.map { |child| invert_predicate(child) })
+          when SearchEngine::AST::Group
+            SearchEngine::AST.group(invert_predicate(node.child))
           else
-            out_nodes << SearchEngine::DSL::Parser.parse({ field => value }, klass: @klass, joins: joins_list)
+            raise SearchEngine::Errors::InvalidOperator, "where.not cannot invert a #{node.type} predicate"
           end
         end
 
@@ -478,10 +429,6 @@ module SearchEngine
           end
         end
 
-        def emit_empty_array_flag(out_nodes, lhs, negated)
-          out_nodes << SearchEngine::AST.raw("#{lhs}:=#{negated ? 'false' : 'true'}")
-        end
-
         def base_empty_filtering_enabled?(field_sym)
           opts = @klass.respond_to?(:attribute_options) ? (@klass.attribute_options || {}) : {}
           o = opts[field_sym]
@@ -526,59 +473,6 @@ module SearchEngine
           false
         end
 
-        def emit_nil_flags_for_base(out_nodes, field_sym, negated)
-          has_empty = base_empty_filtering_enabled?(field_sym)
-          has_blank = base_optional_enabled?(field_sym)
-          fragment = nil
-          if has_empty && has_blank
-            fragment = if negated
-                         "(#{field_sym}_empty:=false && #{field_sym}_blank:=false)"
-                       else
-                         "(#{field_sym}_empty:=true || #{field_sym}_blank:=true)"
-                       end
-          elsif has_blank
-            fragment = "#{field_sym}_blank:=#{negated ? 'false' : 'true'}"
-          elsif has_empty
-            fragment = "#{field_sym}_empty:=#{negated ? 'false' : 'true'}"
-          end
-
-          out_nodes << if fragment
-                         SearchEngine::AST.raw(fragment)
-                       else
-                         SearchEngine::DSL::Parser.parse({ field_sym => nil }, klass: @klass, joins: joins_list)
-                       end
-        end
-
-        def emit_nil_flags_for_join(out_nodes, assoc_sym, field_sym, negated)
-          has_empty = joined_empty_filtering_enabled?(assoc_sym, field_sym)
-          has_blank = joined_optional_enabled?(assoc_sym, field_sym)
-          lhs_empty = "$#{assoc_sym}.#{field_sym}_empty"
-          lhs_blank = "$#{assoc_sym}.#{field_sym}_blank"
-          fragment = nil
-          if has_empty && has_blank
-            fragment = if negated
-                         "(#{lhs_empty}:=false && #{lhs_blank}:=false)"
-                       else
-                         "(#{lhs_empty}:=true || #{lhs_blank}:=true)"
-                       end
-          elsif has_blank
-            fragment = "#{lhs_blank}:=#{negated ? 'false' : 'true'}"
-          elsif has_empty
-            fragment = "#{lhs_empty}:=#{negated ? 'false' : 'true'}"
-          end
-
-          if fragment
-            out_nodes << SearchEngine::AST.raw(fragment)
-          else
-            parsed = { assoc_sym => { field_sym => nil } }
-            out_nodes << SearchEngine::DSL::Parser.parse(parsed, klass: @klass, joins: joins_list)
-          end
-        end
-
-        def array_like?(value)
-          value.is_a?(Array)
-        end
-
         def raise_empty_array_type!(field_sym)
           raise SearchEngine::Errors::InvalidType.new(
             %(expected #{field_sym.inspect} to be a non-empty Array),
@@ -591,7 +485,7 @@ module SearchEngine
         def normalize_where(args)
           # Preserve input shape so template bind arrays stay intact:
           # where('field IN ?', [1, 2]) => ['field IN ?', [1, 2]]
-          list = Array(args).compact
+          list = Array(args)
           return [] if list.empty?
 
           fragments = []
@@ -601,6 +495,8 @@ module SearchEngine
           while i < list.length
             entry = list[i]
             case entry
+            when nil
+              i += 1
             when Hash
               # Validate only base-like keys here; assoc keys (values as Hash) are handled via AST/Parser
               # and assoc keys with join-scope shorthand (values as Symbol/Array<Symbol>) are ignored for fragments.
@@ -610,7 +506,7 @@ module SearchEngine
               base_pairs = base_like_pairs
               unless base_pairs.empty?
                 fragments.concat(
-                  SearchEngine::Filters::Sanitizer.build_from_hash(base_pairs, known_attrs)
+                  SearchEngine::Filters::Sanitizer.build_from_hash(base_pairs, known_attrs, klass: @klass)
                 )
               end
               i += 1
@@ -632,15 +528,15 @@ module SearchEngine
         end
 
         def normalize_where_process_string!(fragments, entry, list, i)
-          if entry.match?(/(?<!\\)\?/) # has unescaped placeholders
+          needed = SearchEngine::Filters::Sanitizer.count_placeholders(entry)
+          if needed.positive?
             tail = list[(i + 1)..] || []
-            needed = SearchEngine::Filters::Sanitizer.count_placeholders(entry)
             args_for_template = tail.first(needed)
             if args_for_template.length != needed
               raise ArgumentError, "expected #{needed} args for #{needed} placeholders, got #{args_for_template.length}"
             end
 
-            fragments << SearchEngine::Filters::Sanitizer.apply_placeholders(entry, args_for_template)
+            fragments << SearchEngine::Filters::Sanitizer.apply_placeholders(entry, args_for_template, klass: @klass)
             i + 1 + needed
           else
             fragments << entry.to_s

data/lib/search_engine/relation/dx.rb

@@ -153,7 +153,9 @@ module SearchEngine
           seg << 'missing_values' if g[:missing_values]
           parts << "grouping=#{seg.join(':')}"
         end
-        if params.key?(:page) || params.key?(:per_page)
+        if params.key?(:offset)
+          parts << "offset/limit=#{params[:offset]}/#{params[:limit]}"
+        elsif params.key?(:page) || params.key?(:per_page)
           p = params[:page]
           per = params[:per_page]
           parts << "page/per=#{p || ''}/#{per || ''}"

data/lib/search_engine/relation/materializers.rb

@@ -53,7 +53,8 @@ module SearchEngine
 
       # Find the first matching record using where-like inputs.
       # Accepts the same arguments as `.where` (Hash, String, Array, Symbol),
-      # applies them if provided, then limits to a single result and returns it.
+      # and fetches one hit. Page-based searches start at the first match.
+      # Offset-based searches retain their explicit starting offset.
       #
       # @param args [Array<Object>] where-compatible arguments
       # @return [Object, nil]
@@ -61,8 +62,10 @@ module SearchEngine
       #   SearchEngine::Product.find_by(article_code: 12312, store_id: 1031)
       #   SearchEngine::Product.where(active: true).find_by('price:>100')
       def find_by(*args)
-        relation = args.nil? || args.empty? ? self : where(*args)
-        relation.per(1).page(1).first
+        relation = where(*args)
+        return relation.limit(1).first if compute_pagination.key?(:offset)
+
+        relation.page(1).per(1).first
       end
 
       # Convenience for plucking :id values.

data/lib/search_engine/relation/options.rb

@@ -5,33 +5,12 @@ module SearchEngine
     # Options and pagination normalization helpers.
     # Centralizes precedence rules and guards for page/per vs limit/offset.
     module Options
-      # Compute page/per_page with precedence:
-      # - When page/per are provided, prefer them (fill missing per with nil, page defaults to 1 when only per is set)
-      # - Otherwise, when limit is set, derive page from offset and per_page from limit
-      # - Otherwise, return empty Hash
-      # @return [Hash{Symbol=>Integer}]
+      # Page-based pagination takes precedence. A native offset can start between pages.
       def compute_pagination
-        page = @state[:page]
-        per = @state[:per_page]
-
-        if page || per
-          out = {}
-          if per && page
-            out[:page] = page
-            out[:per_page] = per
-          elsif per && !page
-            out[:page] = 1
-            out[:per_page] = per
-          elsif page && !per
-            out[:page] = page
-          end
-          return out
-        elsif @state[:limit]
-          limit = @state[:limit]
-          off = @state[:offset] || 0
-          computed_page = (off.to_i / limit.to_i) + 1
-          return { page: computed_page, per_page: limit }
-        end
+        page, per, limit, offset = @state.values_at(:page, :per_page, :limit, :offset)
+        return { page: page || 1, per_page: per }.compact if page || per
+        return { offset: offset, limit: limit }.compact if offset
+        return { page: 1, per_page: limit } if limit
 
         {}
       end

data/lib/search_engine/relation/state.rb

@@ -128,8 +128,9 @@ module SearchEngine
         legacy = Array(state[:filters]).flatten.compact
         return if !ast_nodes.empty? || legacy.empty?
 
-        raw_nodes = legacy.map { |fragment| SearchEngine::AST.raw(String(fragment)) }
-        state[:ast] = raw_nodes
+        state[:ast] = legacy.map { |fragment| SearchEngine::AST.raw(String(fragment)) }
+        # On a subsequent spawn, '?' in these compiled literals is data.
+        state[:filters] = []
         nil
       end
 

data/lib/search_engine/relation.rb

@@ -17,7 +17,7 @@ module SearchEngine
       find_index index rindex values_at sample shuffle rotate
     ].freeze
     # Keys considered essential for :only preset mode.
-    ESSENTIAL_PARAM_KEYS = %i[q page per_page].freeze
+    ESSENTIAL_PARAM_KEYS = %i[q page per_page offset limit].freeze
 
     # @return [Class] bound model class (typically a SearchEngine::Base subclass)
     attr_reader :klass
@@ -463,8 +463,9 @@ module SearchEngine
         parts << gparts.join(' ')
       end
 
-      parts << "page=#{compiled[:page]}" if compiled.key?(:page)
-      parts << "per=#{compiled[:per_page]}" if compiled.key?(:per_page)
+      { page: :page, per: :per_page, offset: :offset, limit: :limit }.each do |label, key|
+        parts << "#{label}=#{compiled[key]}" if compiled.key?(key)
+      end
 
       "#<#{self.class.name} #{parts.join(' ')} >"
     end
@@ -586,7 +587,7 @@ module SearchEngine
         msg,
         hint: 'Increase `validate_hits!(max:)` or narrow filters. Prefer `limit_hits(n)` to avoid work when supported.',
         doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/hit-limits#validation',
-        details: { total_hits: th, max: max, collection: coll, relation_summary: inspect }
+        details: { total_hits: th, max: max, collection: coll, relation_summary: summary_inspect_string }
       )
     end
 

data/lib/search_engine/result.rb

@@ -105,6 +105,26 @@ module SearchEngine
       freeze
     end
 
+    # Apply relation constraints to a result supplied by a custom client.
+    # Matching model instances, including all grouped hits, can be shared.
+    def with_context(klass:, selection:, facets:)
+      return Result.new(raw, klass: klass, selection: selection, facets: facets) unless klass == @klass
+
+      copy = dup
+      copy.send(:apply_context!, selection, facets)
+      copy.freeze
+    end
+
+    # Source documents aligned with #hits, or with every hit in each group.
+    def self.documents(raw, all_group_members: false)
+      groups = raw['grouped_hits'] || raw[:grouped_hits]
+      (groups || [raw]).flat_map do |section|
+        hits = section['hits'] || section[:hits]
+        docs = Array(hits).filter_map { |hit| hit['document'] || hit[:document] }
+        groups && !all_group_members ? docs.first(1) : docs
+      end
+    end
+
     # Iterate over hydrated hits.
     # @yieldparam obj [Object] hydrated object
     # @return [Enumerator] when no block is given
@@ -314,6 +334,17 @@ module SearchEngine
       end
     end
 
+    def apply_context!(selection, facets)
+      @selection_ctx = selection
+      if selection && selection[:strict_missing]
+        Result.documents(raw, all_group_members: true).each do |document|
+          enforce_strict_missing_if_needed!(document.keys.map(&:to_s))
+        end
+      end
+      @facets_ctx = facets
+      @__facets_parsed_memo = build_parsed_facets(raw, facets).freeze if facets
+    end
+
     def parse_facets
       @__facets_parsed_memo || {}.freeze
     end
@@ -504,12 +535,12 @@ module SearchEngine
 
     # Enforce strict-missing behavior when enabled.
     # Computes missing = requested_root − present_keys and raises when non-empty.
-    def enforce_strict_missing_if_needed!(present_keys)
+    def enforce_strict_missing_if_needed!(present_keys, requested_override: nil)
       ctx = @selection_ctx || {}
       strict = (ctx[:strict_missing] == true)
       return unless strict
 
-      requested = Array(ctx[:requested_root]).map(&:to_s).reject(&:empty?)
+      requested = Array(requested_override || ctx[:requested_root]).map(&:to_s).reject(&:empty?)
       return if requested.empty?
 
       missing = requested - present_keys

data/lib/search_engine/schema.rb

@@ -161,9 +161,9 @@ module SearchEngine
       # physical name). If no block is given, and the klass responds to
       # `reindex_all_to(physical_name)`, that method will be called. If neither is available,
       # an ArgumentError is raised and no alias swap occurs. If reindexing fails or
-      # is interrupted, the newly created physical collection is automatically deleted
-      # to prevent orphan accumulation. Retention cleanup only runs after a successful
-      # alias swap.
+      # is interrupted, the unused new physical is cleaned up. Once an alias swap is
+      # attempted, an error can leave its outcome unknown. Both generations are kept
+      # for reconciliation. Retention cleanup only runs after a successful cutover.
       #
       # @param klass [Class] model class inheriting from {SearchEngine::Base}
       # @param client [SearchEngine::Client] optional client wrapper (for tests)
@@ -201,8 +201,11 @@ module SearchEngine
         end
       end
 
-      def with_around_rebuild(logical)
+      def with_around_rebuild(logical, require_guard: false)
         guard = SearchEngine.config.schema.around_rebuild
+        if require_guard && !guard
+          raise ArgumentError, 'rollback expected_current requires schema.around_rebuild to serialize alias writers'
+        end
         return yield unless guard
 
         result = nil
@@ -237,10 +240,6 @@ module SearchEngine
       private :with_around_rebuild
 
       def perform_full_rebuild!(klass, client:, compiled:, logical:, reindex_step:)
-        new_physical = nil
-        physical_created = false
-        apply_succeeded = false
-
         cleanup_logical_collection_conflict!(logical, client: client)
 
         start_ms = monotonic_ms
@@ -260,7 +259,7 @@ module SearchEngine
         end
 
         client.create_collection(create_schema)
-        physical_created = true
+        cleanup_physical = new_physical
 
         if reindex_step
           reindex_step.call(new_physical)
@@ -270,11 +269,11 @@ module SearchEngine
           raise ArgumentError, 'reindex step is required: provide a block or implement klass.reindex_all_to(name)'
         end
 
-        # Idempotent: if alias already points to new physical, treat as no-op
         current_after_reindex = client.resolve_alias(logical)
         swapped = current_after_reindex != new_physical
+        # A timed-out alias PUT may still commit, even after a read sees the old target.
+        cleanup_physical = nil
         client.upsert_alias(logical, new_physical) if swapped
-        apply_succeeded = true
 
         # Retention cleanup
         _, dropped = enforce_retention!(logical, new_physical, client: client, keep_last: effective_keep_last(klass))
@@ -305,7 +304,7 @@ module SearchEngine
           action: :rebuild
         }
       ensure
-        cleanup_interrupted_physical!(new_physical, client) if physical_created && !apply_succeeded
+        cleanup_interrupted_physical!(logical, cleanup_physical, client) if cleanup_physical
       end
       private :perform_full_rebuild!
 
@@ -314,8 +313,9 @@ module SearchEngine
       # With no explicit target, the safe legacy form only rolls the newest physical
       # back one generation. Repeating the same call is a no-op instead of toggling
       # the alias forward again. Use +to+ when orphaned/newer physicals make the
-      # implicit destination ambiguous. +expected_current+ adds compare-and-swap
-      # protection; a retry that already reached +to+ remains successful.
+      # implicit destination ambiguous. +expected_current+ requires an exclusive
+      # +schema.around_rebuild+ guard shared by all alias writers across processes.
+      # A retry that already reached +to+ remains successful.
       #
       # Alias resolution, validation, and the swap all run inside
       # +schema.around_rebuild+ when configured, so delivery claims and cooperating
@@ -335,7 +335,7 @@ module SearchEngine
         destination = normalize_rollback_target(to, 'to')
         expected = normalize_rollback_target(expected_current, 'expected_current')
 
-        with_around_rebuild(logical) do
+        with_around_rebuild(logical, require_guard: !expected.nil?) do
           perform_rollback!(
             logical,
             client: client,
@@ -615,16 +615,15 @@ module SearchEngine
 
       private
 
-      # Best-effort cleanup of a physical collection left behind by an interrupted
-      # or failed {.apply!}. Rescues all errors so it never masks the original
-      # exception. If the delete itself fails, a warning directs users to
-      # {.prune_orphans!} as a fallback.
+      # Clean up a failed rebuild before cutover only if the alias is known to
+      # point elsewhere. Preserve the original exception if inspection or deletion fails.
       #
-      # @param physical_name [String, nil] the physical collection to remove
-      # @param client [SearchEngine::Client, nil]
+      # @param logical [String] alias for the rebuilt collection
+      # @param physical_name [String] the physical collection to remove
+      # @param client [SearchEngine::Client]
       # @return [void]
-      def cleanup_interrupted_physical!(physical_name, client)
-        return if physical_name.nil? || client.nil?
+      def cleanup_interrupted_physical!(logical, physical_name, client)
+        return if client.resolve_alias(logical) == physical_name
 
         client.delete_collection(physical_name, timeout_ms: 60_000)
 
@@ -637,7 +636,7 @@ module SearchEngine
       rescue StandardError => error
         warn(
           'SearchEngine::Schema — failed to clean up interrupted physical ' \
-          "'#{physical_name}': #{error.message}. Run prune_orphans! to remove it."
+          "'#{physical_name}': #{error.message}. Verify alias '#{logical}' before pruning unused generations."
         )
       end
 

data/lib/search_engine/test/offline_client.rb

@@ -13,11 +13,11 @@ module SearchEngine
       EMPTY_SEARCH = { 'hits' => [], 'found' => 0, 'out_of' => 0 }.freeze
 
       def search(collection:, params:, url_opts: {})
-        SearchEngine::Result.new(EMPTY_SEARCH, klass: nil)
+        block_given? ? yield(EMPTY_SEARCH) : SearchEngine::Result.new(EMPTY_SEARCH, klass: nil)
       end
 
       def multi_search(searches:, url_opts: {})
-        { 'results' => [] }
+        { 'results' => searches.map { EMPTY_SEARCH } }
       end
 
       def import_documents(collection:, jsonl:, action: :upsert)