search-engine-for-typesense 30.9.1 → 30.9.3

data/lib/search_engine/compiler.rb

@@ -70,26 +70,12 @@ module SearchEngine
 
     def compile_node(node, parent_prec:, klass: nil)
       case node
-      when SearchEngine::AST::Eq
-        compile_binary(node.field, ':=', node.value, klass: klass)
-      when SearchEngine::AST::NotEq
-        compile_binary(node.field, ':!=', node.value, klass: klass)
-      when SearchEngine::AST::Gt
-        compile_binary(node.field, ':>', node.value, klass: klass)
-      when SearchEngine::AST::Gte
-        compile_binary(node.field, ':>=', node.value, klass: klass)
-      when SearchEngine::AST::Lt
-        compile_binary(node.field, ':<', node.value, klass: klass)
-      when SearchEngine::AST::Lte
-        compile_binary(node.field, ':<=', node.value, klass: klass)
-      when SearchEngine::AST::In
-        compile_binary(node.field, ':=', node.values, klass: klass)
-      when SearchEngine::AST::NotIn
-        compile_binary(node.field, ':!=', node.values, klass: klass)
+      when SearchEngine::AST::BinaryOp
+        compile_binary(node, klass: klass)
       when SearchEngine::AST::And
         compile_boolean(node.children, ' && ', parent_prec: parent_prec, my_prec: precedence(:and), klass: klass)
       when SearchEngine::AST::Or
-        compile_or(node, parent_prec, klass: klass)
+        compile_boolean(node.children, ' || ', parent_prec: parent_prec, my_prec: precedence(:or), klass: klass)
       when SearchEngine::AST::Group
         "(#{compile_node(node.children.first, parent_prec: 0, klass: klass)})"
       when SearchEngine::AST::Raw
@@ -104,61 +90,24 @@ module SearchEngine
     end
     private_class_method :compile_node
 
-    def compile_or(node, parent_prec, klass: nil)
-      compiled = compile_boolean(
-        node.children,
-        ' || ',
-        parent_prec: parent_prec,
-        my_prec: precedence(:or),
-        klass: klass
-      )
-      if node.children.length == 2 && node.children.last.is_a?(SearchEngine::AST::And)
-        left_str, right_str = compiled.split(' || ', 2)
-        compiled = "#{left_str} || (#{right_str})"
+    def compile_binary(node, klass:)
+      if (joined = extract_join_inner_binary(node, klass: klass))
+        assoc, inner = joined
+        return "$#{assoc}(#{inner})"
       end
-      compiled
-    end
-    private_class_method :compile_or
-
-    def compile_binary(field, op, value, klass: nil)
-      fstr = field.to_s
-      if (m = fstr.match(/^\$(\w+)\.(.+)$/))
-        assoc = m[1]
-        inner = m[2]
-        # Render joined field as $assoc(inner OP value) per expected Typesense join filter syntax
-        target_klass = begin
-          cfg = klass.respond_to?(:join_for) ? klass.join_for(assoc.to_sym) : nil
-          coll = cfg ? cfg[:collection] : nil
-          coll ? SearchEngine.collection_for(coll) : nil
-        rescue StandardError
-          nil
-        end
-        rhs = quote(value, field: inner, klass: target_klass || klass)
-        "$#{assoc}(#{inner}#{op}#{rhs})"
-      else
-        rhs = quote(value, field: fstr, klass: klass)
-        binary(field, op, rhs)
-      end
-    end
-    private_class_method :compile_binary
 
-    def binary(field, op, rhs)
-      "#{field}#{op}#{rhs}"
+      "#{node.field}#{op_for(node)}#{quote(node.right, field: node.field, klass: klass)}"
     end
-    private_class_method :binary
+    private_class_method :compile_binary
 
     def compile_boolean(children, joiner, parent_prec:, my_prec:, klass: nil)
       # For conjunctions only, merge multiple $assoc(inner ...) predicates targeting
       # the same association into a single $assoc(inner && inner ...) expression
       # to satisfy Typesense join filter rules.
       if joiner == ' && '
-        merged = merge_join_predicates(children, parent_prec: parent_prec, my_prec: my_prec, klass: klass,
-joiner: joiner
-        )
-        return merged if merged
+        return merge_join_predicates(children, parent_prec: parent_prec, my_prec: my_prec, klass: klass)
       end
 
-      # Fallback/default behavior
       parts = children.map do |child|
         cstr = compile_node(child, parent_prec: my_prec, klass: klass)
         if needs_parentheses?(child, parent_prec: my_prec)
@@ -188,40 +137,26 @@ joiner: joiner
     # @param parent_prec [Integer] parent operator precedence
     # @param my_prec [Integer] current operator precedence
     # @param klass [Class, nil] model class for context
-    # @param joiner [String] operator joiner (' && ' or ' || ')
-    # @return [String, nil] merged expression string, or nil if no joins to merge
-    def merge_join_predicates(children, parent_prec:, my_prec:, klass:, joiner:)
-      items = [] # [{ pos:, str: }]
-      assoc_first_pos = {}
-      assoc_inner_map = {} # { assoc => [inner_str, ...] }
-
-      children.each_with_index do |child, idx|
-        inner = extract_join_inner_binary(child, klass: klass)
-        if inner
-          assoc, inner_expr = inner
-          assoc_first_pos[assoc] = idx unless assoc_first_pos.key?(assoc)
-          assoc_inner_map[assoc] ||= []
-          assoc_inner_map[assoc] << inner_expr
+    # @return [String] compiled conjunction
+    def merge_join_predicates(children, parent_prec:, my_prec:, klass:)
+      groups = {}
+      parts = children.map.with_index do |child, position|
+        if (joined = extract_join_inner_binary(child, klass: klass))
+          assoc, predicate = joined
+          group = groups[assoc] ||= { position: position, predicates: [] }
+          group[:predicates] << predicate
           next
         end
 
-        cstr = compile_node(child, parent_prec: my_prec, klass: klass)
-        cstr = "(#{cstr})" if needs_parentheses?(child, parent_prec: my_prec)
-        items << { pos: idx, str: cstr }
+        expression = compile_node(child, parent_prec: my_prec, klass: klass)
+        needs_parentheses?(child, parent_prec: my_prec) ? "(#{expression})" : expression
       end
 
-      return nil if assoc_inner_map.empty?
-
-      # Emit one consolidated token per assoc at the first position it appeared
-      assoc_first_pos.sort_by { |_a, pos| pos }.each do |assoc, pos|
-        inners = Array(assoc_inner_map[assoc]).flatten.compact
-        next if inners.empty?
-
-        token = "$#{assoc}(#{inners.join(' && ')})"
-        items << { pos: pos, str: token }
+      groups.each do |assoc, group|
+        parts[group[:position]] = "$#{assoc}(#{group[:predicates].join(' && ')})"
       end
 
-      inner = items.sort_by { |it| it[:pos] }.map { |it| it[:str] }.join(joiner)
+      inner = parts.compact.join(' && ')
       parent_prec > my_prec ? "(#{inner})" : inner
     end
     private_class_method :merge_join_predicates
@@ -229,37 +164,12 @@ joiner: joiner
     # Try to extract join association and compiled inner expression for a binary node
     # with a joined field like "$assoc.field". Returns [assoc(String), inner(String)] or nil.
     def extract_join_inner_binary(node, klass: nil)
-      case node
-      when SearchEngine::AST::Eq, SearchEngine::AST::NotEq,
-           SearchEngine::AST::Gt, SearchEngine::AST::Gte,
-           SearchEngine::AST::Lt, SearchEngine::AST::Lte,
-           SearchEngine::AST::In, SearchEngine::AST::NotIn
-        field = node.respond_to?(:field) ? node.field.to_s : nil
-        return nil unless field&.start_with?('$')
-
-        m = field.match(/^\$(\w+)\.(.+)$/)
-        return nil unless m
-
-        assoc = m[1]
-        inner_field = m[2]
-        op = op_for(node)
-        target_klass = begin
-          cfg = klass.respond_to?(:join_for) ? klass.join_for(assoc.to_sym) : nil
-          coll = cfg ? cfg[:collection] : nil
-          coll ? SearchEngine.collection_for(coll) : nil
-        rescue StandardError
-          nil
-        end
-        rhs = if node.respond_to?(:value)
-                quote(node.value, field: inner_field, klass: target_klass || klass)
-              elsif node.respond_to?(:values)
-                quote(node.values, field: inner_field, klass: target_klass || klass)
-              else
-                return nil
-              end
-
-        [assoc, "#{inner_field}#{op}#{rhs}"]
-      end
+      return unless node.is_a?(SearchEngine::AST::BinaryOp) && node.field.start_with?('$')
+
+      assoc, field = node.field.delete_prefix('$').split('.', 2)
+      target = SearchEngine::Joins::Guard.target_model(klass, assoc)
+      rhs = quote(node.right, field: field, klass: target, joined: true)
+      [assoc, "#{field}#{op_for(node)}#{rhs}"]
     end
     private_class_method :extract_join_inner_binary
 
@@ -274,12 +184,12 @@ joiner: joiner
       when SearchEngine::AST::In then ':='
       when SearchEngine::AST::NotIn then ':!='
       else
-        raise Error, "Unknown binary node for join extraction: #{node.class}"
+        raise Error, "Compiler: unsupported binary predicate #{node.class}"
       end
     end
     private_class_method :op_for
 
-    def quote(value, field: nil, klass: nil)
+    def quote(value, field:, klass:, joined: false)
       # Typesense requires reference fields to use string values, even if the field type is int64
       converted_value = if klass && field && field_reference?(klass, field)
                           convert_for_reference_field(value)
@@ -287,12 +197,7 @@ joiner: joiner
                           value
                         end
 
-      # Use conditional scalar quoting for scalars; preserve array element quoting rules
-      if converted_value.is_a?(Array)
-        SearchEngine::Filters::Sanitizer.quote(converted_value)
-      else
-        SearchEngine::Filters::Sanitizer.quote_scalar_for_filter(converted_value)
-      end
+      SearchEngine::Filters::Sanitizer.quote(converted_value, field: field, klass: klass, joined: joined)
     end
     private_class_method :quote
 
@@ -333,7 +238,7 @@ joiner: joiner
     def needs_parentheses?(child, parent_prec:)
       child_prec = precedence(child)
       # Parenthesize when child binds looser than parent
-      child_prec < parent_prec
+      child_prec < parent_prec || (child.is_a?(SearchEngine::AST::And) && parent_prec == precedence(:or))
     end
     private_class_method :needs_parentheses?
 

data/lib/search_engine/deletion.rb

@@ -17,7 +17,7 @@ module SearchEngine
     # @param timeout_ms [Integer, nil] optional read timeout override in ms
     # @return [Integer] number of deleted documents as reported by Typesense
     def delete_by(klass:, filter: nil, hash: nil, into: nil, partition: nil, timeout_ms: nil)
-      filter_str = build_filter(filter, hash)
+      filter_str = build_filter(filter, hash, klass: klass)
       collection = resolve_into(klass: klass, partition: partition, into: into)
 
       effective_timeout = if timeout_ms&.to_i&.positive?
@@ -42,15 +42,18 @@ module SearchEngine
     # @param filter [String, nil]
     # @param hash [Hash, nil]
     # @return [String]
-    def build_filter(filter, hash)
-      if filter && !filter.to_s.strip.empty?
-        filter.to_s
-      elsif hash.is_a?(Hash) && !hash.empty?
-        fragments = SearchEngine::Filters::Sanitizer.build_from_hash(hash)
-        fragments.join(' && ')
-      else
-        raise ArgumentError, 'delete_by requires a filter string or a non-empty hash'
+    def build_filter(filter, hash, klass: nil)
+      return filter if filter.is_a?(String) && !filter.strip.empty?
+      unless filter.nil? || filter.is_a?(String) || filter.is_a?(Hash)
+        raise ArgumentError, 'expected a filter string or hash'
       end
+
+      raise ArgumentError, 'provide filter fields in a single hash' if filter.is_a?(Hash) && hash && !hash.empty?
+
+      fields = filter.is_a?(Hash) ? filter : hash
+      raise ArgumentError, 'expected a non-empty filter hash' unless fields.is_a?(Hash) && !fields.empty?
+
+      SearchEngine::Filters::Sanitizer.build_from_hash(fields, klass: klass).join(' && ')
     end
 
     # Resolve the physical collection name using the same logic as the indexer.

data/lib/search_engine/dsl/parser.rb

@@ -47,7 +47,7 @@ module SearchEngine
         when String
           if placeholders?(input)
             needed = count_placeholders(input)
-            ensure_placeholder_arity!(needed, args.length, input)
+            ensure_placeholder_arity!(needed, args.length)
             parse_template(input, args, klass: klass)
           else
             parse_raw(input)
@@ -70,7 +70,7 @@ module SearchEngine
       def parse_list(list, klass:, joins: nil)
         # Preserve input shape so template bind arrays stay intact:
         # parse_list(['brand_id IN ?', [1, 2]]) should keep [1, 2] as one bind arg.
-        items = Array(list).compact
+        items = Array(list)
         return [] if items.empty?
 
         nodes = []
@@ -78,6 +78,8 @@ module SearchEngine
         while i < items.length
           entry = items[i]
           case entry
+          when nil
+            i += 1
           when Hash
             nodes.concat(Array(parse_hash(entry, klass: klass, joins: joins)))
             i += 1
@@ -85,7 +87,7 @@ module SearchEngine
             if placeholders?(entry)
               needed = count_placeholders(entry)
               args_for_template = items[(i + 1)..(i + needed)] || []
-              ensure_placeholder_arity!(needed, args_for_template.length, entry)
+              ensure_placeholder_arity!(needed, args_for_template.length)
               nodes << parse_template(entry, args_for_template, klass: klass)
               i += 1 + needed
             else
@@ -130,7 +132,7 @@ module SearchEngine
                       entry[1..]
                     end
         needed = count_placeholders(template)
-        ensure_placeholder_arity!(needed, Array(args_list).length, template)
+        ensure_placeholder_arity!(needed, Array(args_list).length)
         parse_template(template, Array(args_list), klass: klass)
       end
 
@@ -150,31 +152,25 @@ module SearchEngine
             # assoc => { field => value }
             validate_assoc_and_join!(klass, key_sym, joins)
 
+            cfg = klass.join_for(key_sym)
+            target_klass = SearchEngine::Joins::Guard.target_model(klass, key_sym)
             value.each do |inner_field, inner_value|
               field_sym = inner_field.to_sym
               path = "$#{key_sym}.#{field_sym}"
               SearchEngine::Joins::Guard.ensure_single_hop_path!(path)
 
-              # Resolve target klass for joined-field type coercion and validate field best-effort
-              cfg = klass.join_for(key_sym)
-              target_klass = begin
-                SearchEngine.collection_for(cfg[:collection])
-              rescue StandardError
-                nil
-              end
-              begin
-                SearchEngine::Joins::Guard.validate_joined_field!(cfg, field_sym)
-              rescue StandardError
-                # skip strictly when registry/attributes missing or join missing
+              if target_klass && strict_fields?
+                SearchEngine::Joins::Guard.validate_joined_field!(
+                  cfg, field_sym, source_klass: klass, target_klass: target_klass
+                )
               end
 
-              coercion_klass = target_klass || klass
               if array_like?(inner_value)
-                values = normalize_array_values(inner_value, field: field_sym, klass: coercion_klass)
-                ensure_non_empty_values!(values, field: field_sym, klass: coercion_klass)
+                values = normalize_array_values(inner_value, field: field_sym, klass: target_klass)
+                ensure_non_empty_values!(values, field: field_sym, klass: target_klass)
                 pairs << SearchEngine::AST.in_(path, values)
               else
-                coerced = coerce_value_for_field(inner_value, field: field_sym, klass: coercion_klass)
+                coerced = coerce_value_for_field(inner_value, field: field_sym, klass: target_klass)
                 pairs << SearchEngine::AST.eq(path, coerced)
               end
             end
@@ -204,9 +200,8 @@ module SearchEngine
         m = template.match(/\A\s*([A-Za-z_][A-Za-z0-9_]*)\s*(=|!=|>=|<=|>|<|IN|NOT\s+IN|MATCHES|PREFIX)\s*\?\s*\z/i)
         unless m
           raise SearchEngine::Errors::InvalidOperator.new(
-            "invalid template '#{template}'. Supported: =, !=, >, >=, <, <=, IN, NOT IN, MATCHES, PREFIX",
-            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
-            details: { template: template }
+            'invalid filter template. Supported operators: =, !=, >, >=, <, <=, IN, NOT IN, MATCHES, PREFIX',
+            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting'
           )
         end
 
@@ -266,7 +261,7 @@ module SearchEngine
                         arr[1..]
                       end
           needed = count_placeholders(template)
-          ensure_placeholder_arity!(needed, Array(args_list).length, template)
+          ensure_placeholder_arity!(needed, Array(args_list).length)
           parse_template(template, Array(args_list), klass: klass)
         else
           parse_list(arr, klass: klass, joins: joins)
@@ -283,13 +278,13 @@ module SearchEngine
         SearchEngine::Filters::Sanitizer.count_placeholders(str)
       end
 
-      def ensure_placeholder_arity!(needed, provided, template)
+      def ensure_placeholder_arity!(needed, provided)
         return if needed == provided
 
         raise SearchEngine::Errors::InvalidOperator.new(
-          "expected #{needed} args for #{needed} placeholders in template '#{template}', got #{provided}.",
+          "expected #{needed} args for #{needed} placeholders, got #{provided}.",
           doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
-          details: { needed: needed, provided: provided, template: template }
+          details: { needed: needed, provided: provided }
         )
       end
 
@@ -352,7 +347,7 @@ module SearchEngine
         return if values.is_a?(Array) && !values.empty?
 
         raise SearchEngine::Errors::InvalidType.new(
-          invalid_type_message(field: field, klass: klass, expectation: 'a non-empty Array', got: values),
+          "expected #{field.inspect} to be a non-empty Array for #{klass} (got #{values.class})",
           doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
           details: { field: field, got_class: values.class.name }
         )
@@ -372,7 +367,7 @@ module SearchEngine
         # If generic coercion returned :__no_coercion__, try to coerce based on type hint
         case type_hint
         when :boolean
-          coerce_boolean(value, type_hint)
+          coerce_boolean(value, type_hint, field: field, klass: klass)
         when :time, :datetime, :time_string, :datetime_string
           coerce_time(value, type_hint, field: field, klass: klass)
 
@@ -389,7 +384,7 @@ module SearchEngine
       end
 
       def coerce_value(value, type_hint: nil, field: nil, klass: nil)
-        coerced_bool = coerce_boolean(value, type_hint)
+        coerced_bool = coerce_boolean(value, type_hint, field: field, klass: klass)
         return coerced_bool unless coerced_bool.equal?(:__no_coercion__)
 
         coerced_time = coerce_time(value, type_hint, field: field, klass: klass)
@@ -401,18 +396,14 @@ module SearchEngine
         value
       end
 
-      def coerce_boolean(value, type_hint)
+      def coerce_boolean(value, type_hint, field:, klass:)
         return :__no_coercion__ unless type_boolean?(type_hint) && value.is_a?(String)
 
         lc = value.strip.downcase
         return true if lc == 'true'
         return false if lc == 'false'
 
-        raise SearchEngine::Errors::InvalidType.new(
-          invalid_type_message(field: nil, klass: nil, expectation: 'boolean', got: value),
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
-          details: { got: value }
-        )
+        raise invalid_type(field, klass, 'boolean', value)
       end
       private_class_method :coerce_boolean
 
@@ -439,12 +430,9 @@ module SearchEngine
         else
           :__no_coercion__
         end
-      rescue StandardError
-        raise SearchEngine::Errors::InvalidType.new(
-          invalid_type_message(field: field, klass: klass, expectation: 'time', got: value),
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
-          details: { field: field, got: value }
-        )
+      rescue ArgumentError, TypeError, RangeError
+        # Time.parse includes the input in its exception, which error reporters also traverse.
+        raise invalid_type(field, klass, 'time', value), cause: nil
       end
       private_class_method :coerce_time
 
@@ -453,26 +441,17 @@ module SearchEngine
           return value if value.is_a?(Integer)
 
           if value.is_a?(String)
-            begin
-              int_val = Integer(value, 10)
-              return int_val
-            rescue StandardError
-              raise SearchEngine::Errors::InvalidType.new(
-                invalid_type_message(field: field, klass: klass, expectation: 'integer', got: value),
-                doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
-                details: { field: field, got: value }
-              )
-            end
-          end
+            number = Integer(value, 10, exception: false)
+            raise invalid_type(field, klass, 'integer', value) unless number
+
+            # Typesense compares document IDs byte-for-byte. Converting "0042" would target "42".
+            return value if field.to_s == 'id' && value != number.to_s
 
-          if value.is_a?(Numeric)
-            raise SearchEngine::Errors::InvalidType.new(
-              invalid_type_message(field: field, klass: klass, expectation: 'integer', got: value),
-              doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
-              details: { field: field, got: value }
-            )
+            return number
           end
 
+          raise invalid_type(field, klass, 'integer', value) if value.is_a?(Numeric)
+
           return :__no_coercion__
         end
 
@@ -481,16 +460,10 @@ module SearchEngine
           return value.to_f if value.is_a?(Numeric)
 
           if value.is_a?(String)
-            begin
-              Float(value)
-            rescue StandardError
-              raise SearchEngine::Errors::InvalidType.new(
-                invalid_type_message(field: field, klass: klass, expectation: 'numeric', got: value),
-                doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
-                details: { field: field, got: value }
-              )
-            end
-            return value.to_f
+            number = Float(value, exception: false)
+            raise invalid_type(field, klass, 'numeric', value) unless number
+
+            return number
           end
         end
 
@@ -568,10 +541,17 @@ module SearchEngine
         best.first.to_sym
       end
 
-      def invalid_type_message(field:, klass:, expectation:, got:)
-        klass_name = klass.respond_to?(:name) && klass.name ? klass.name : klass.to_s
-        %(expected #{field.inspect} to be #{expectation} for #{klass_name} (got #{got.class}: #{got.inspect}))
+      def invalid_type(field, klass, expectation, value)
+        subject = field ? field.inspect : 'filter value'
+        model = " for #{klass}" if klass
+        actual = value.class.name
+        SearchEngine::Errors::InvalidType.new(
+          "expected #{subject} to be #{expectation}#{model} (got #{actual})",
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
+          details: { field: field, expected: expectation, got: actual }
+        )
       end
+      private_class_method :invalid_type
 
       def validate_assoc_and_join!(klass, assoc_name, joins)
         # Validate association exists and config completeness

data/lib/search_engine/engine.rb

@@ -35,13 +35,7 @@ module SearchEngine
 
       # Also ensure Rails global autoloaders ignore these files, since the engine
       # adds lib/ to autoload paths and the main/once loaders may scan it.
-      if defined?(Rails) && Rails.respond_to?(:autoloaders)
-        al = Rails.autoloaders
-        al.main.ignore(shim) if al.respond_to?(:main)
-        al.once.ignore(shim) if al.respond_to?(:once)
-        al.main.ignore(cli_file) if al.respond_to?(:main)
-        al.once.ignore(cli_file) if al.respond_to?(:once)
-      end
+      Rails.autoloaders.each { |autoloader| autoloader.ignore(shim, cli_file) }
     end
 
     initializer 'search_engine.observability' do
@@ -111,6 +105,26 @@ module SearchEngine
       end
     end
 
+    # Rails-managed mappers may declare a collection unrelated to their constant name.
+    # Register these mappings before a callback can interpret a miss as a bare collection.
+    initializer 'search_engine.rails_model_mappings' do |app|
+      app.reloader.to_prepare do
+        models = app.paths['app/models'].existent
+        if Rails.autoloaders.zeitwerk_enabled?
+          Rails.autoloaders.each do |loader|
+            (loader.dirs & models).each do |root|
+              namespace_dir = File.join(root, 'search_engine')
+              loader.eager_load_dir(namespace_dir) if File.directory?(namespace_dir)
+            end
+          end
+        else
+          models.each do |root|
+            Dir[File.join(root, 'search_engine', '**', '*.rb')].sort.each { |file| require_dependency(file) }
+          end
+        end
+      end
+    end
+
     # Manage a dedicated Zeitwerk loader for host app SearchEngine models.
     # Loads after Rails so application models/constants are available.
     initializer 'search_engine.models_loader' do
@@ -126,22 +140,17 @@ module SearchEngine
       next unless File.directory?(path_s)
 
       # Ensure Rails' autoloaders do not also manage this directory.
-      if defined?(Rails) && Rails.respond_to?(:autoloaders)
-        al = Rails.autoloaders
-        %i[main once].each do |key|
-          al.public_send(key).ignore(path_s) if al.respond_to?(key)
-        end
-      end
+      Rails.autoloaders.each { |autoloader| autoloader.ignore(path_s) }
 
       # Create or reuse a dedicated loader under SearchEngine namespace.
       loader = SearchEngine.instance_variable_get(:@_models_loader)
       unless loader
+        require 'zeitwerk'
         loader = Zeitwerk::Loader.new
         loader.tag = 'search_engine.models'
         # Reuse Rails' inflector for consistent constantization rules.
-        if defined?(Rails) && Rails.respond_to?(:autoloaders) && Rails.autoloaders.respond_to?(:main)
-          loader.inflector = Rails.autoloaders.main.inflector
-        end
+        main = Rails.autoloaders.main
+        loader.inflector = main.inflector if main
         loader.push_dir(path_s, namespace: SearchEngine)
         loader.enable_reloading if defined?(Rails) && Rails.env.development?
         SearchEngine.instance_variable_set(:@_models_loader, loader)