parse-stack-next 5.7.6 → 5.8.1

data/lib/parse/query.rb

@@ -209,8 +209,8 @@ module Parse
     #   # Valid values: :primary, :primary_preferred, :secondary, :secondary_preferred, :nearest
     #  @return [Symbol, String] the read preference for this query.
     attr_reader :table, :session_token
-    attr_writer :client
-    attr_accessor :key, :cache, :use_master_key, :verbose_aggregate, :read_preference
+    attr_accessor :key, :cache, :verbose_aggregate, :read_preference
+    attr_reader :use_master_key
 
     # We have a special class method to handle field formatting. This turns
     # the symbol keys in an operand from one key to another. For example, we can
@@ -225,6 +225,32 @@ module Parse
     @field_formatter = :columnize
     @allow_scope_introspection = false
 
+    # Fiber-local scope used by {Parse::Query.format_field} to honor a
+    # model's explicit `field:` names while a query compiles.
+    # Stored in inheritable fiber storage (`Fiber[]`), so a fiber or thread
+    # started while a query compiles sees the same names, and an assignment in
+    # the child never leaks back to the parent. The value is a
+    # {FieldAliasFrame} (or nil when no query is compiling). The frame is
+    # closed when the block that opened it returns, so a long-lived thread
+    # started during a compile stops using that query's names afterwards.
+    FIELD_ALIAS_SCOPE_KEY = :parse_query_field_alias_scope
+    EMPTY_FIELD_ALIASES = {}.freeze
+    FIELD_ALIAS_CACHE_MAX = 1_000
+    FIELD_ALIAS_CACHE_MUTEX = Mutex.new
+    # @!visibility private
+    # One cached alias map for a table, stamped with the model registry
+    # generation and the model's field_map size it was built from.
+    FieldAliasScope = Struct.new(:table, :aliases, :generation, :klass, :field_count)
+    # @!visibility private
+    # One {with_field_aliases} activation: the scope plus whether the block
+    # that set it is still running.
+    FieldAliasFrame = Struct.new(:scope, :aliases, :open)
+    # Per-table {FieldAliasScope} cache. Replaced (never mutated) under the
+    # mutex, so readers need no lock.
+    @field_alias_cache = {}.freeze
+    # System fields with their own handling, never treated as aliases.
+    FIELD_ALIAS_BUILTINS = %w[id created_at updated_at acl].freeze
+
     # The set of symbol keys that {#conditions} treats as query-shape
     # options (cache TTL, ordering, limits, ACL convenience helpers,
     # session/master-key overrides) rather than as field-name
@@ -303,14 +329,159 @@ module Parse
 
       # @param str [String] the string to format
       # @return [String] formatted string using {Parse::Query.field_formatter}.
+      #   While a query is compiling, a name the query's model declares with
+      #   an explicit `field:` (for example `property :account_id, field:
+      #   :account_id` or `field: :authId_sub`) is returned exactly as
+      #   declared, whether the caller used the Ruby name or the remote name.
       def format_field(str)
         res = str.to_s.strip
+        frame = Fiber[FIELD_ALIAS_SCOPE_KEY]
+        if frame && frame.open && (mapped = frame.aliases[res])
+          return mapped
+        end
         if field_formatter.present? && res.respond_to?(field_formatter)
           res = res.send(field_formatter)
         end
         res
       end
 
+      # Run the block with `table`'s explicit field aliases in effect for
+      # {format_field}. Always sets the scope (possibly to an empty map), so
+      # a subquery on another class, compiled inside an outer query, uses its
+      # own model's names. Re-entering for the table already in scope just
+      # yields. The scope lives in inheritable fiber storage, so concurrent
+      # queries on other threads or fibers are isolated.
+      #
+      # @param table [String] the Parse class name.
+      # @return the block's value
+      def with_field_aliases(table)
+        table = table.to_s unless table.nil? || table.is_a?(String)
+        previous = Fiber[FIELD_ALIAS_SCOPE_KEY]
+        return yield if table == (previous && previous.open ? previous.scope.table : nil)
+        scope = field_alias_scope_for(table)
+        frame = FieldAliasFrame.new(scope, scope.aliases, true)
+        begin
+          Fiber[FIELD_ALIAS_SCOPE_KEY] = frame
+          yield
+        ensure
+          frame.open = false
+          Fiber[FIELD_ALIAS_SCOPE_KEY] = previous
+        end
+      end
+
+      # @!visibility private
+      # The {FieldAliasScope} in effect, or nil. A frame inherited from a
+      # block that has since returned is ignored.
+      # @return [FieldAliasScope, nil]
+      def current_field_alias_scope
+        frame = Fiber[FIELD_ALIAS_SCOPE_KEY]
+        frame.scope if frame && frame.open
+      end
+
+      # @!visibility private
+      # The Parse class whose aliases are in scope, or nil.
+      # @return [String, nil]
+      def field_alias_table
+        current_field_alias_scope&.table
+      end
+
+      # @!visibility private
+      # Wrap a caller's block so it runs with the alias scope that was active
+      # before the query method opened its own. Without this, a block passed
+      # to `results`, `first`, `each`, and similar would format another
+      # class's keys (a pointer `fetch(keys:)`, a cursor, a nested query
+      # helper) with the outer model's names.
+      #
+      # @param blk [Proc, nil] the caller's block.
+      # @param table [String, nil] the table the scope is about to be set to.
+      # @return [Proc, nil]
+      def block_outside_field_aliases(blk, table)
+        return blk if blk.nil?
+        outer = Fiber[FIELD_ALIAS_SCOPE_KEY]
+        table = table.to_s unless table.nil? || table.is_a?(String)
+        # Re-entrant call for the table already in scope: the block either
+        # belongs to the caller that opened it or is internal.
+        return blk if table == (outer && outer.open ? outer.scope.table : nil)
+        wrapped = proc do |*args, &inner|
+          scoped = Fiber[FIELD_ALIAS_SCOPE_KEY]
+          Fiber[FIELD_ALIAS_SCOPE_KEY] = outer
+          begin
+            blk.call(*args, &inner)
+          ensure
+            Fiber[FIELD_ALIAS_SCOPE_KEY] = scoped
+          end
+        end
+        wrapped.ruby2_keywords
+        wrapped
+      end
+
+      # The explicit remote names a model declares: every `field_map` entry
+      # whose remote name differs from what {format_field} would produce
+      # for the Ruby name. Maps both the Ruby name and the remote name to the
+      # remote name, so `where(account_id:)` and `where("account_id" =>)`
+      # both compile to the declared column. Names the model does not alias
+      # are absent, so they keep the default formatting.
+      #
+      # Cached per table. An entry is reused until a model is defined, a
+      # `parse_class` is set, or a field is declared (see
+      # {Parse::Model.model_generation}), or until the model's `field_map`
+      # grows (associations add entries there directly).
+      #
+      # @param table [String]
+      # @return [Hash{String => String}]
+      def field_aliases_for(table)
+        field_alias_scope_for(table).aliases
+      end
+
+      # @!visibility private
+      # @param table [String, nil]
+      # @return [FieldAliasScope] the cached scope for `table`.
+      def field_alias_scope_for(table)
+        key = table.to_s
+        generation = Parse::Model.model_generation
+        entry = @field_alias_cache[key]
+        if entry && entry.generation == generation &&
+           (entry.klass.nil? || entry.klass.field_map.size == entry.field_count)
+          return entry
+        end
+
+        klass = (Parse::Model.find_class(key) rescue nil)
+        klass = nil unless klass.respond_to?(:field_map)
+        aliases = klass ? build_field_aliases(klass.field_map) : EMPTY_FIELD_ALIASES
+        entry = FieldAliasScope.new(table, aliases, generation, klass,
+                                    klass ? klass.field_map.size : 0).freeze
+        FIELD_ALIAS_CACHE_MUTEX.synchronize do
+          cache = @field_alias_cache
+          cache = {} if cache.size >= FIELD_ALIAS_CACHE_MAX
+          @field_alias_cache = cache.merge(key => entry).freeze
+        end
+        entry
+      end
+
+      # @!visibility private
+      # The query-side view of {Parse::Model.field_resolution_map}: the same
+      # resolution rule (Ruby property name first, then an exact declared
+      # column), keeping only the names whose column differs from the default
+      # lowerCamelCase form. Every other name keeps {field_formatter}
+      # (including nil) exactly as before.
+      #
+      # @param fmap [Hash{Symbol => Symbol}] a model's field_map.
+      # @return [Hash{String => String}] frozen alias map.
+      def build_field_aliases(fmap)
+        # Built-in system fields keep their existing handling, under both
+        # their Ruby and their column names.
+        builtin_wires = FIELD_ALIAS_BUILTINS.filter_map { |b| fmap[b.to_sym]&.to_s }
+        aliases = {}
+        Parse::Model.field_resolution_map(fmap).each do |name, wire|
+          next if wire == name.columnize
+          next if FIELD_ALIAS_BUILTINS.include?(name) || builtin_wires.include?(name)
+          # Never let an alias address an internal Parse Server column.
+          next if wire.start_with?("_")
+          aliases[name] = wire
+        end
+        aliases.empty? ? EMPTY_FIELD_ALIASES : aliases.freeze
+      end
+
       # Convert camelCase string to snake_case
       # @param str [String] the camelCase string
       # @return [String] the snake_case string
@@ -399,29 +570,157 @@ module Parse
         constraint_reduce(where)
       end
 
+      # SDK routing markers that a REST `$or` branch cannot carry.
+      # @!visibility private
+      OR_BRANCH_MARKERS = %w[__aggregation_pipeline __mongo_direct_only].freeze
+
       # @!visibility private
+      # Compile one branch of an OR group. A constraint that only works
+      # through the aggregation pipeline or mongo-direct (`readable_by`,
+      # `:ACL.readable_by`, `:tags.array_size`, the mongo-direct geo
+      # operators) compiles to a routing marker that {compile_where}
+      # strips. Inside an OR that would turn the branch into `{}`, which
+      # matches every row, or silently drop part of it. Such a branch is
+      # refused instead.
+      # @param where [Array<Parse::Constraint>]
+      # @return [Hash] the compiled branch.
+      # @raise [ArgumentError] when the branch carries a routing marker.
+      def compile_or_branch(where)
+        markers = compile_markers(where)
+        if or_branch_marker?(markers)
+          names = pipeline_only_constraint_names(where)
+          raise ArgumentError,
+                "This constraint is not supported inside an OR " \
+                "(#{names.empty? ? "pipeline-only constraint" : names.join(", ")}): it needs the " \
+                "aggregation pipeline or mongo-direct, and a REST `$or` branch cannot carry it. " \
+                "Apply it outside the OR, or run the OR branches as separate queries."
+        end
+        compile_where(where)
+      end
+
+      # @!visibility private
+      # Names (`field.operator`) of the constraints in a where list that
+      # compile to a pipeline or mongo-direct routing marker.
+      # @return [Array<String>]
+      def pipeline_only_constraint_names(where)
+        Array(where).select { |c| c.is_a?(Parse::Constraint) && or_branch_marker?(c.as_json) }
+                    .map do |c|
+                      field = c.operand.to_s.casecmp?("acl") ? "ACL" : c.operand.to_s
+                      c.operation.respond_to?(:operator) ? "#{field}.#{c.operation.operator}" : field
+                    end.uniq
+      end
+
+      # @!visibility private
+      def or_branch_marker?(value)
+        case value
+        when Hash
+          value.any? { |k, v| OR_BRANCH_MARKERS.include?(k.to_s) || or_branch_marker?(v) }
+        when Array
+          value.any? { |v| or_branch_marker?(v) }
+        else
+          false
+        end
+      end
+
+      # @!visibility private
+      # Reduce a list of constraints into one where hash. Constraints on the
+      # same field are combined so every one of them still applies:
+      #
+      # * Operator hashes with distinct operators merge
+      #   (`:plays.gt => 1` and `:plays.lt => 9` give `{"$gt" => 1, "$lt" => 9}`).
+      # * An equality next to operators becomes `$eq`
+      #   (`:plays => 5` and `:plays.gt => 1` give `{"$eq" => 5, "$gt" => 1}`).
+      # * Anything that cannot merge without changing its meaning (the same
+      #   operator with a different value, two different equalities, two
+      #   regular expressions, two `$or` groups) is kept in a top-level `$and`,
+      #   so both conditions must hold. The first constraint keeps the field
+      #   key and each later conflicting one is appended to `$and`.
+      #
+      # Identical constraints collapse to one.
       def constraint_reduce(clauses)
-        # @todo Need to add proper constraint merging
         clauses.reduce({}) do |clause, subclause|
-          #puts "Merging Subclause: #{subclause.as_json}"
-
           subclause_json = subclause.as_json || {}
+          subclause_json.each { |key, value| merge_constraint_entry!(clause, key, value) }
+          clause
+        end
+      end
+
+      # Operators whose meaning depends on a partner operator in the same
+      # hash. Two hashes that both use one of a group are never merged.
+      COUPLED_OPERATOR_GROUPS = [
+        %w[$regex $options],
+        %w[$near $nearSphere $maxDistance $maxDistanceInRadians $maxDistanceInMiles
+           $maxDistanceInKilometers $geoWithin $geoIntersects $within],
+        %w[$text $search],
+      ].freeze
 
-          # Special handling for aggregation pipeline constraints
-          # Instead of overwriting, concatenate the pipeline arrays
-          if clause.key?("__aggregation_pipeline") && subclause_json.key?("__aggregation_pipeline")
-            clause["__aggregation_pipeline"].concat(subclause_json["__aggregation_pipeline"])
-            # Don't merge the __aggregation_pipeline key using deep_merge
-            subclause_without_pipeline = subclause_json.reject { |k, v| k == "__aggregation_pipeline" }
-            clause.deep_merge!(subclause_without_pipeline)
+      # @!visibility private
+      def merge_constraint_entry!(clause, key, value)
+        unless clause.key?(key)
+          clause[key] = value.is_a?(Array) && key == "__aggregation_pipeline" ? value.dup : value
+          return
+        end
+        existing = clause[key]
+        return if existing == value
+
+        if key == "__aggregation_pipeline" || (key == "$and" && existing.is_a?(Array) && value.is_a?(Array))
+          clause[key] = existing + value
+        elsif key.is_a?(String) && key.start_with?("__")
+          # SDK-internal routing markers keep their previous merge behavior.
+          clause[key] = existing.is_a?(Hash) && value.is_a?(Hash) ? existing.deep_merge(value) : value
+        elsif operator_hash?(existing) && operator_hash?(value)
+          if mergeable_operator_hashes?(existing, value)
+            clause[key] = existing.merge(value)
           else
-            clause.deep_merge!(subclause_json)
+            append_and_constraint!(clause, key, value)
           end
-
-          clause
+        elsif operator_hash?(existing) && !operator_value_key?(key)
+          eq = { "$eq" => value }
+          if mergeable_operator_hashes?(existing, eq)
+            clause[key] = existing.merge(eq)
+          else
+            append_and_constraint!(clause, key, value)
+          end
+        elsif operator_hash?(value) && !operator_value_key?(key)
+          eq = { "$eq" => existing }
+          if mergeable_operator_hashes?(eq, value)
+            clause[key] = eq.merge(value)
+          else
+            append_and_constraint!(clause, key, value)
+          end
+        else
+          append_and_constraint!(clause, key, value)
         end
       end
 
+      # @!visibility private
+      def append_and_constraint!(clause, key, value)
+        list = clause["$and"]
+        clause["$and"] = (list.is_a?(Array) ? list : []) + [{ key => value }]
+      end
+
+      # @!visibility private
+      # A top-level operator key (`$or`, `$relatedTo`) holds a value, not a
+      # field constraint.
+      def operator_value_key?(key)
+        key.to_s.start_with?("$")
+      end
+
+      # @!visibility private
+      def operator_hash?(value)
+        value.is_a?(Hash) && !value.empty? && value.each_key.all? { |k| k.to_s.start_with?("$") }
+      end
+
+      # @!visibility private
+      def mergeable_operator_hashes?(a, b)
+        a_ops = a.transform_keys(&:to_s)
+        b_ops = b.transform_keys(&:to_s)
+        a_keys = a_ops.keys
+        b_keys = b_ops.keys
+        return false if (a_keys & b_keys).any? { |op| a_ops[op] != b_ops[op] }
+        COUPLED_OPERATOR_GROUPS.none? { |group| (a_keys & group).any? && (b_keys & group).any? }
+      end
+
       # Applies special singleton methods to a query instance in order to
       # automatically fetch results when using any ruby console.
       # @!visibility private
@@ -441,6 +740,14 @@ module Parse
       @client ||= self.class.client
     end
 
+    # Set the client this query runs through. A client from
+    # {Parse::Client#become} carries a session, so on a query combined
+    # with OR the change is checked like any other change of authority.
+    # @param value [Parse::Client]
+    def client=(value)
+      guard_or_scope_change { @client = value }
+    end
+
     # Clear a specific clause of this query. This can be one of: :where, :order,
     # :includes, :skip, :limit, :count, :keys or :results.
     # @param item [:Symbol] the clause to clear.
@@ -521,6 +828,11 @@ module Parse
     #   and their value.
     # @return [self]
     def conditions(expressions = {})
+      # Apply `:or` last, so a `:session` or `:use_master_key` in the same
+      # Hash is in place before the branches' authority is compared.
+      if expressions.is_a?(Hash) && expressions.key?(:or) && expressions.keys.last != :or
+        expressions = expressions.reject { |k, _| k == :or }.merge(or: expressions[:or])
+      end
       expressions.each do |expression, value|
         # Normalize to symbol for comparison (handles both string and symbol keys)
         expr_sym = expression.respond_to?(:to_sym) ? expression.to_sym : expression
@@ -588,6 +900,9 @@ module Parse
           not_publicly_readable if value
         elsif expr_sym == :not_publicly_writable
           not_publicly_writable if value
+        elsif expression == :or
+          # Symbol key only: a string "or" stays a literal field name.
+          add_or_branches(value)
         else
           add_constraint(expression, value)
         end
@@ -595,6 +910,114 @@ module Parse
       self #chaining
     end
 
+    # @!visibility private
+    # Handle the `:or => [branch, ...]` condition. Each branch is a
+    # constraint Hash, a {Parse::Query}, or an Array of {Parse::Constraint}.
+    # The branches are ORed together and the group is ANDed with the
+    # query's other constraints. A branch with no constraints matches every
+    # row, so the group adds no constraint. An empty list matches no rows.
+    # @param branches [Array]
+    def add_or_branches(branches)
+      unless branches.is_a?(Array)
+        raise ArgumentError, ":or expects an Array of constraint hashes or queries, got #{branches.class}."
+      end
+      with_or_rollback { add_or_branches_unguarded(branches) }
+    end
+
+    # @!visibility private
+    def add_or_branches_unguarded(branches)
+      wheres = branches.map do |branch|
+        case branch
+        when Parse::Query
+          unless branch.table == @table
+            raise ArgumentError, ":or branch queries must be of the same class #{@table} (got #{branch.table})."
+          end
+          # The branch's authority travels with its conditions, or raises
+          # when it differs from this query's.
+          merge_or_scope!(branch)
+          branch.where
+        when Hash then or_branch_hash_where(branch)
+        when Array
+          # A branch given as a list: constraints, or constraint hashes that
+          # are expanded the same way a Hash branch is. Anything else is
+          # refused, so a typo cannot empty the branch and turn it into
+          # match-all.
+          branch.flat_map do |item|
+            case item
+            when Parse::Constraint then [item]
+            when Hash then or_branch_hash_where(item)
+            else
+              raise ArgumentError, ":or Array branches may only hold Parse::Constraint objects or constraint hashes, got #{item.class}."
+            end
+          end
+        else
+          raise ArgumentError, ":or branches must be constraint hashes or Parse::Query objects, got #{branch.class}."
+        end
+      end
+      if wheres.empty?
+        # `$or: []` is rejected by MongoDB. Keep the "no rows" meaning.
+        add_constraint(:objectId.in, [])
+        return
+      end
+      # Refuse pipeline-only constraints in any branch before deciding
+      # whether the group is match-all.
+      compiled = wheres.map { |w| Parse::Query.compile_or_branch(w) }
+      return if wheres.any? { |w| Parse::Query.match_all?(w) }
+      add_constraint(Parse::Constraint::CompoundQueryConstraint.new(:or, compiled), nil, filter: false)
+    end
+    private :add_or_branches_unguarded
+
+    # @!visibility private
+    # Query options that shape a whole query and mean nothing inside one OR
+    # branch.
+    OR_BRANCH_OPTION_KEYS = %i[order keys key skip limit include includes cache read_preference].freeze
+
+    # @!visibility private
+    # The constraints of a Hash OR branch. The branch is built as its own
+    # query so a `session:` / `use_master_key:` key or a nested `:or` with a
+    # scoped query is applied there, and its authority then has to agree
+    # with this query's (adopted when this query has none, refused when it
+    # differs). Query-shaping options inside a branch are refused.
+    # @param hash [Hash]
+    # @return [Array<Parse::Constraint>]
+    def or_branch_hash_where(hash)
+      options = hash.keys.select { |k| k.is_a?(Symbol) && OR_BRANCH_OPTION_KEYS.include?(k) }
+      if options.any?
+        raise ArgumentError,
+              "#{options.map(&:inspect).join(", ")} cannot be set inside an OR branch; " \
+              "set it on the query itself."
+      end
+      branch = Parse::Query.new(@table, hash)
+      merge_or_scope!(branch)
+      branch.where
+    end
+    private :or_branch_hash_where
+
+    # @!visibility private
+    # Run an OR or subquery merge so that a raise leaves this query exactly
+    # as it was: constraints, authority, client, and the pinned authority.
+    def with_or_rollback
+      # Captured before the guarded block: a failure here changes nothing,
+      # so there is nothing to restore.
+      ivars = OR_SCOPE_STATE_IVARS + %i[@_or_branch_scope @_or_branch_app @read_preference]
+      saved = ivars.to_h { |iv| [iv, [instance_variable_defined?(iv), instance_variable_get(iv)]] }
+      saved_where = @where.dup
+      begin
+        yield
+      rescue StandardError
+        saved.each do |iv, (defined, value)|
+          if defined
+            instance_variable_set(iv, value)
+          elsif instance_variable_defined?(iv)
+            remove_instance_variable(iv)
+          end
+        end
+        @where = saved_where
+        raise
+      end
+    end
+    private :with_or_rollback
+
     alias_method :query, :conditions
     alias_method :append, :conditions
 
@@ -607,11 +1030,16 @@ module Parse
         value = value.session_token
       end
 
-      if value.nil? || (value.is_a?(String) && value.present?)
-        @session_token = value
-      else
+      unless value.nil? || (value.is_a?(String) && value.present?)
         raise ArgumentError, "Invalid session token passed to query."
       end
+      guard_or_scope_change { @session_token = value }
+    end
+
+    # @param value [Boolean, nil] whether to send the master key (nil
+    #   leaves the decision to the request layer).
+    def use_master_key=(value)
+      guard_or_scope_change { @use_master_key = value }
     end
 
     # returns the query clause for the particular clause
@@ -761,11 +1189,16 @@ module Parse
         case entry
         when Order
           entry.field = Query.format_field(entry.field)
-          @order.push entry
-        when Symbol, String
-          o = Order.new(entry)
-          o.field = Query.format_field(o.field)
-          @order.push o
+          push_order(entry)
+        when String
+          if entry.include?(",")
+            # The REST sort string lists several fields: "title,-plays".
+            order(*entry.split(",").map(&:strip).reject(&:empty?))
+            next
+          end
+          push_order(parse_order_string(entry))
+        when Symbol
+          push_order(parse_order_string(entry))
         when Hash
           entry.each do |field, direction|
             dir_sym = direction.is_a?(String) ? direction.downcase.to_sym : direction
@@ -776,7 +1209,7 @@ module Parse
             end
             o = Order.new(field, dir_sym)
             o.field = Query.format_field(o.field)
-            @order.push o
+            push_order(o)
           end
         else
           raise ArgumentError,
@@ -789,6 +1222,38 @@ module Parse
       self #chaining
     end #order
 
+    # @!visibility private
+    # One field of the REST sort-string form: "-title" is descending and
+    # "+title" ascending. Parsing the sign here keeps a repeated field
+    # deduplicated and gives the direct `$sort` stage a real field name.
+    # @return [Parse::Order]
+    def parse_order_string(entry)
+      name = entry.to_s
+      o = if name.start_with?("-") && name.length > 1
+          Order.new(name[1..], :desc)
+        elsif name.start_with?("+") && name.length > 1
+          Order.new(name[1..], :asc)
+        else
+          Order.new(entry)
+        end
+      o.field = Query.format_field(o.field)
+      o
+    end
+    private :parse_order_string
+
+    # @!visibility private
+    # Add one sort key. A field that is already in the order keeps its
+    # position and takes the new direction, so it is sent once. Parse Server
+    # and MongoDB both resolve a repeated sort key the same way.
+    def push_order(order)
+      index = @order.index { |existing| existing.field.to_s == order.field.to_s }
+      if index
+        @order[index] = order
+      else
+        @order.push order
+      end
+    end
+
     # Use with limit to paginate through results. Default is 0.
     # @example
     #  # get the next 3 songs after the first 10
@@ -937,6 +1402,7 @@ module Parse
     # @return [self]
     def add_constraints(list)
       list = Array.wrap(list).select { |m| m.is_a?(Parse::Constraint) }
+      list.each { |c| merge_subquery_scopes!(c.value) }
       @where = @where + list
       self
     end
@@ -975,11 +1441,31 @@ module Parse
         constraint.operand = Query.format_field(constraint.operand)
       end
       reject_vector_constraint!(constraint)
+      merge_subquery_scopes!(constraint.value)
       @where.push constraint
       @results = nil
       self #chaining
     end
 
+    # @!visibility private
+    # Parse Server runs a subquery (`$inQuery`, `$notInQuery`, `$select`,
+    # `$dontSelect`) under the outer request's authority, so a subquery's
+    # own session or scope has to agree with this query's: it is adopted
+    # when this query has none and refused when it differs, the same rule
+    # as an OR branch.
+    def merge_subquery_scopes!(value)
+      subqueries = case value
+        when Parse::Query then [value]
+        when Hash
+          q = value[:query] || value["query"]
+          q.is_a?(Parse::Query) ? [q] : []
+        else []
+        end
+      return if subqueries.empty?
+      with_or_rollback { subqueries.each { |q| merge_or_scope!(q) } }
+    end
+    private :merge_subquery_scopes!
+
     # @!visibility private
     # Raise {Parse::VectorSearch::ConstraintNotSupported} when a
     # constraint targets a declared `:vector` property with an operator
@@ -1078,24 +1564,41 @@ module Parse
     # @param where_clauses [Array<Parse::Constraint>] a list of Parse::Constraint objects to combine.
     # @return [Query] the combined query with an OR clause.
     def or_where(where_clauses = [])
-      where_clauses = where_clauses.where if where_clauses.is_a?(Parse::Query)
-      where_clauses = Parse::Query.new(@table, where_clauses).where if where_clauses.is_a?(Hash)
+      with_or_rollback { or_where_unguarded(where_clauses) }
+    end
+
+    # @!visibility private
+    def or_where_unguarded(where_clauses)
+      if where_clauses.is_a?(Parse::Query)
+        unless where_clauses.table == @table
+          raise ArgumentError, "Parse queries must be of the same class #{@table}."
+        end
+        merge_or_scope!(where_clauses)
+        # A query with no constraints is a branch that matches every row, so
+        # the whole OR does too.
+        return match_all! if Parse::Query.match_all?(where_clauses.where)
+        where_clauses = where_clauses.where
+      end
+      where_clauses = or_branch_hash_where(where_clauses) if where_clauses.is_a?(Hash)
       return self if where_clauses.blank?
-      # we can only have one compound query constraint. If we need to add another OR clause
-      # let's find the one we have (if any)
-      compound = @where.find { |f| f.is_a?(Parse::Constraint::CompoundQueryConstraint) }
-      # create a set of clauses that are not an OR clause.
-      remaining_clauses = @where.select { |f| f.is_a?(Parse::Constraint::CompoundQueryConstraint) == false }
+      # Reuse the existing OR only when it is the query's sole constraint.
+      # When other constraints sit beside it, the current where is
+      # `(A or B) and C`, so that whole expression becomes one branch of the
+      # new OR. Appending to the existing OR would silently drop `C`.
+      compound = nil
+      if @where.size == 1 && @where.first.is_a?(Parse::Constraint::CompoundQueryConstraint)
+        compound = @where.first
+      end
       # if we don't have a OR clause to reuse, then create a new one with then
       # current set of constraints
       if compound.blank?
-        initial_constraints = Parse::Query.compile_where(remaining_clauses)
+        initial_constraints = Parse::Query.compile_or_branch(@where)
         # Only include initial constraints if they're not empty
         initial_values = initial_constraints.empty? ? [] : [initial_constraints]
         compound = Parse::Constraint::CompoundQueryConstraint.new :or, initial_values
       end
       # then take the where clauses from the second query and append them.
-      new_constraints = Parse::Query.compile_where(where_clauses)
+      new_constraints = Parse::Query.compile_or_branch(where_clauses)
       # Only add new constraints if they're not empty
       unless new_constraints.empty?
         compound.value.push new_constraints
@@ -1104,16 +1607,330 @@ module Parse
       @where = [compound]
       self #chaining
     end
+    private :or_where_unguarded
 
+    # Combine two queries with OR. The result is a copy of the receiver
+    # (its limit, order, keys and includes) whose where is the OR of both.
+    #
+    # * A receiver with no constraints is a starting point, the same as
+    #   {#or_where}: `Model.query | q` gives an OR whose only branch is `q`,
+    #   so `[q1, q2].reduce(Model.query, :|)` gives `q1 OR q2`.
+    # * A right-hand side with no constraints is a branch that matches
+    #   every row, so `q | Model.query` has no constraints.
+    #
+    # The auth scope (session token, master-key flag, `scope_to_user`,
+    # `scope_to_role`) carries over from whichever side set it. Two
+    # different scopes raise `ArgumentError`, since the OR could only run
+    # under one of them.
     # @see #or_where
     # @return [Query] the combined query with an OR clause.
+    # @raise [ArgumentError] when the classes or auth scopes differ, or a
+    #   branch holds a pipeline-only constraint.
     def |(other_query)
       raise ArgumentError, "Parse queries must be of the same class #{@table}." unless @table == other_query.table
       copy_query = self.clone
-      copy_query.or_where other_query.where
+      copy_query.send(:merge_or_scope!, other_query)
+      if Parse::Query.match_all?(other_query.where)
+        # Still refuse a pipeline-only receiver rather than silently
+        # widening it.
+        Parse::Query.compile_or_branch(@where)
+        copy_query.match_all!
+      else
+        copy_query.or_where other_query.where
+      end
       copy_query
     end
 
+    # @!visibility private
+    # Auth scope ivars an OR must agree on.
+    OR_SCOPE_IVARS = %i[session_token use_master_key acl_user acl_role].freeze
+
+    # @!visibility private
+    # The authority this query runs under, as one comparable Hash: the
+    # session token, the scoped user id, the scoped role name, and an
+    # explicit master-key flag. An explicit `use_master_key = false` beside
+    # a session, user, or role adds nothing, since those already run without
+    # the master key. An empty Hash is the default authority.
+    # @return [Hash]
+    def or_effective_scope
+      scope = {}
+      scope[:session] = @session_token unless @session_token.nil?
+      # A client from Parse::Client#become sends its bound session on every
+      # request that names no token and does not ask for the master key,
+      # so it counts as that session. A non-default client with neither a
+      # session nor a master key runs without the master key.
+      own_client = or_explicit_client
+      if own_client && @session_token.nil? && @use_master_key != true
+        bound = own_client.respond_to?(:session_token) ? own_client.session_token : nil
+        if bound.is_a?(String) && !bound.strip.empty?
+          scope[:session] = bound
+        elsif !(own_client.respond_to?(:master_key) && own_client.master_key.present?)
+          scope[:master] = false
+        end
+      end
+      scope[:user] = Parse::Query.or_scope_value(:acl_user, @acl_user) unless @acl_user.nil?
+      scope[:role] = Parse::Query.or_scope_value(:acl_role, @acl_role) unless @acl_role.nil?
+      unless @use_master_key.nil? || (@use_master_key == false && !scope.empty?)
+        scope[:master] = @use_master_key
+      end
+      scope.delete(:master) if scope[:master] == false && scope.size > 1
+      scope
+    end
+    protected :or_effective_scope
+
+    # @!visibility private
+    # The client set on this query when it is not the default client, or
+    # nil. Read from the instance variable so it never memoizes the default.
+    # @return [Parse::Client, nil]
+    def or_explicit_client
+      own = @client
+      return nil if own.nil?
+      default = begin
+          self.class.client
+        rescue StandardError
+          nil
+        end
+      return nil if default && own.equal?(default)
+      own
+    end
+    protected :or_explicit_client
+
+    # @!visibility private
+    # Instance variables that make up a query's authority.
+    OR_SCOPE_STATE_IVARS = %i[@session_token @use_master_key @acl_user @acl_role @client].freeze
+
+    # @!visibility private
+    # Run an assignment that may change this query's authority. On a query
+    # combined with OR, a change that leaves the pinned authority raises
+    # and the previous values are restored, so a rescued error never
+    # leaves the query running under a different principal.
+    def guard_or_scope_change
+      return yield if @_or_branch_scope.nil?
+      saved = OR_SCOPE_STATE_IVARS.to_h { |iv| [iv, instance_variable_get(iv)] }
+      begin
+        yield
+        enforce_or_branch_scope!
+      rescue StandardError
+        saved.each { |iv, v| instance_variable_set(iv, v) }
+        raise
+      end
+    end
+    private :guard_or_scope_change
+
+    # @!visibility private
+    # Combine `other`'s authority with this query's for an OR. Both must
+    # run under the same authority: a query with the default authority
+    # adopts the other's, and two different authorities (a session and a
+    # scoped user, a session and the master key, two users) raise. The
+    # resulting authority is then pinned whichever side carried it, so a
+    # later change to this query's
+    # session, master-key flag, or scope raises instead of running the
+    # other query's rows under a different principal. Read preference is
+    # carried over but a mismatch keeps this query's value.
+    # @param other [Parse::Query]
+    def merge_or_scope!(other)
+      merge_or_application!(other)
+      theirs = other.or_effective_scope
+      if theirs.empty?
+        # The other query has the default authority: pin this query's own
+        # authority, so the result does not depend on operand order.
+        mine = or_effective_scope
+        unless mine.empty?
+          @_or_branch_scope = mine
+          @_or_branch_app = or_application_identity
+        end
+      else
+        mine = or_effective_scope
+        if mine.empty?
+          OR_SCOPE_IVARS.each do |ivar|
+            instance_variable_set(:"@#{ivar}", other.instance_variable_get(:"@#{ivar}"))
+          end
+          adopt_or_client!(other, theirs)
+          # Fail closed if the adopted state still does not reproduce the
+          # other query's authority.
+          unless or_effective_scope == theirs
+            raise ArgumentError,
+                  "Cannot combine with OR a query running under #{Parse::Query.describe_or_scope(theirs)} " \
+                  "through its own client. Run the queries separately."
+          end
+        elsif mine != theirs
+          raise ArgumentError,
+                "Queries combined with OR must run under the same authority " \
+                "(#{Parse::Query.describe_or_scope(mine)} vs #{Parse::Query.describe_or_scope(theirs)}). " \
+                "Run them separately, or set the same scope on each."
+        end
+        @_or_branch_scope = theirs
+        @_or_branch_app = or_application_identity
+      end
+      @read_preference ||= other.read_preference
+      self
+    end
+    protected :merge_or_scope!
+
+    # @!visibility private
+    # The client set on this query when it is a real Parse client other
+    # than the default one, or nil.
+    # @return [Parse::Client, nil]
+    def or_application_client
+      own = or_explicit_client
+      return nil unless own.respond_to?(:application_id) && own.respond_to?(:server_url)
+      own
+    end
+    protected :or_application_client
+
+    # @!visibility private
+    # The application this query runs against, as [application id, server
+    # URL], from its own client or the default client. nil when no client
+    # can be resolved.
+    # @return [Array<String>, nil]
+    def or_application_identity
+      target = or_application_client || begin
+          self.class.client
+        rescue StandardError
+          nil
+        end
+      return nil unless target.respond_to?(:application_id) && target.respond_to?(:server_url)
+      [target.application_id.to_s, target.server_url.to_s.chomp("/")]
+    end
+    protected :or_application_identity
+
+    # @!visibility private
+    # Queries combined with OR must target the same application, so a
+    # session token or master-key authority from one app is never sent to
+    # another. An empty receiver on the default client (no constraints, no
+    # authority) takes the other query's client, as it takes its authority;
+    # any other mismatch raises.
+    def merge_or_application!(other)
+      mine = or_application_identity
+      theirs = other.or_application_identity
+      return if mine.nil? || theirs.nil? || mine == theirs
+      their_client = other.or_application_client
+      if their_client && or_application_client.nil? && @_or_branch_scope.nil? &&
+         or_effective_scope.empty? && Parse::Query.match_all?(@where)
+        @client = their_client
+        return
+      end
+      raise ArgumentError,
+            "Queries combined with OR must run against the same Parse application " \
+            "(#{mine.first} at #{mine.last} vs #{theirs.first} at #{theirs.last}). " \
+            "Run them separately on their own clients."
+    end
+    private :merge_or_application!
+
+    # @!visibility private
+    # Carry `other`'s client-bound authority onto this query. A query with
+    # no client of its own takes `other`'s client, which keeps its server
+    # and session. A query with its own client takes the derived session
+    # token (or the no-master-key flag) explicitly instead.
+    def adopt_or_client!(other, theirs)
+      their_client = other.or_explicit_client
+      return if their_client.nil?
+      if or_explicit_client.nil?
+        @client = their_client
+      elsif other.session_token.nil? && theirs.key?(:session)
+        @session_token = theirs[:session]
+      elsif theirs[:master] == false
+        @use_master_key = false
+      end
+    end
+    private :adopt_or_client!
+
+    # @!visibility private
+    # Raise when this query's authority no longer matches the one an OR
+    # branch was combined under.
+    def enforce_or_branch_scope!
+      return if @_or_branch_scope.nil?
+      if @_or_branch_app && (app = or_application_identity) && app != @_or_branch_app
+        raise ArgumentError,
+              "This query was combined with OR against Parse application #{@_or_branch_app.first}; " \
+              "running it against #{app.first} would send its authority to another application. " \
+              "Build a new query instead."
+      end
+      current = or_effective_scope
+      return if current == @_or_branch_scope
+      raise ArgumentError,
+            "This query was combined with OR under #{Parse::Query.describe_or_scope(@_or_branch_scope)}; " \
+            "changing it to #{Parse::Query.describe_or_scope(current)} would run the combined " \
+            "branches under a different authority. Build a new query instead."
+    end
+    private :enforce_or_branch_scope!
+
+    # @!visibility private
+    # On a query combined with OR, auth kwargs passed straight to a direct
+    # or Atlas terminal (`results_direct(master: true)`) must name the same
+    # authority the query was pinned to, and an explicit client the same
+    # application. A narrower `master: false` is allowed.
+    def enforce_explicit_auth_against_or_scope!(session_token: nil, master: nil, acl_user: nil, acl_role: nil, client: nil)
+      return if @_or_branch_scope.nil?
+      if client && @_or_branch_app && client.respond_to?(:application_id) && client.respond_to?(:server_url)
+        app = [client.application_id.to_s, client.server_url.to_s.chomp("/")]
+        unless app == @_or_branch_app
+          raise ArgumentError,
+                "This query was combined with OR against Parse application #{@_or_branch_app.first}; " \
+                "the client: passed here targets #{app.first}."
+        end
+      end
+      given = {}
+      token = session_token.respond_to?(:session_token) ? session_token.session_token : session_token
+      given[:session] = token unless token.nil?
+      given[:user] = Parse::Query.or_scope_value(:acl_user, acl_user) unless acl_user.nil?
+      given[:role] = Parse::Query.or_scope_value(:acl_role, acl_role) unless acl_role.nil?
+      given[:master] = true if master && master != false
+      return if given.empty? || given == @_or_branch_scope
+      raise ArgumentError,
+            "This query was combined with OR under #{Parse::Query.describe_or_scope(@_or_branch_scope)}; " \
+            "the auth passed here (#{Parse::Query.describe_or_scope(given)}) would run it under a " \
+            "different authority."
+    end
+    private :enforce_explicit_auth_against_or_scope!
+
+    # @!visibility private
+    # A redacted, human-readable form of an authority Hash for errors.
+    def self.describe_or_scope(scope)
+      return "the default authority" if scope.empty?
+      scope.map do |kind, value|
+        case kind
+        when :session then "a session token"
+        when :user then "scoped user #{value}"
+        when :role then "scoped role #{value}"
+        when :master then value ? "the master key" : "no master key"
+        end
+      end.join(" + ")
+    end
+
+    # @!visibility private
+    # A comparable form of one auth scope value.
+    def self.or_scope_value(ivar, value)
+      case ivar
+      when :acl_user
+        value.respond_to?(:id) ? value.id : value.to_s
+      when :acl_role
+        name = value.respond_to?(:name) ? value.name : value.to_s
+        name.to_s.delete_prefix("role:")
+      else
+        value
+      end
+    end
+
+    # @!visibility private
+    # Drop every where constraint, so the query matches all rows.
+    # @return [self]
+    def match_all!
+      @where = []
+      @results = nil
+      self
+    end
+    protected :match_all!
+
+    # @!visibility private
+    # Whether a list of constraints places no restriction on the rows (an
+    # empty list, or constraints that compile to nothing).
+    # @param where [Array<Parse::Constraint>]
+    # @return [Boolean]
+    def self.match_all?(where)
+      where.blank? || compile_markers(where).empty?
+    end
+
     # Add a "field is NOT between" condition — the logical negation of
     # `.where(field.between => value)`: `field < min OR field > max` for a
     # fully-bounded Range/Array, or a single one-sided comparison when the
@@ -1260,7 +2077,7 @@ module Parse
       values = raw_results.map { |item| item["value"] }.compact
 
       # Use schema-based approach to handle pointer field results
-      parse_class = Parse::Model.const_get(@table) rescue nil
+      parse_class = table_model_class
       is_pointer = parse_class && is_pointer_field?(parse_class, field, formatted_field)
 
       if is_pointer && values.any?
@@ -1423,9 +2240,13 @@ module Parse
         { "$count" => "distinctCount" },
       ]
 
+      # `limit(0)` selects no rows.
+      return 0 if @limit == 0
+
       # Use the Aggregation class to execute
-      # The aggregate method will automatically handle where conditions
-      aggregation = aggregate(pipeline, verbose: @verbose_aggregate)
+      # The aggregate method will automatically handle where conditions,
+      # and the query's order / skip / limit pick the rows before `$group`.
+      aggregation = aggregate(pipeline, verbose: @verbose_aggregate, window_before_pipeline: true)
       raw_results = aggregation.raw
 
       # Extract the count from the response
@@ -1481,35 +2302,36 @@ module Parse
         return first_direct(limit_or_constraints)
       end
 
-      if limit_or_constraints.is_a?(Hash)
-        conditions(limit_or_constraints)
-        # Check if limit was set in constraints, otherwise use 1
-        # Handle :max case - if @limit is :max, default to 1 for first()
-        fetch_count = (@limit.is_a?(Numeric) ? @limit : nil) || 1
-        # Set @limit to ensure query only fetches the needed records
-        @results = nil if @limit != fetch_count
-        @limit = fetch_count
-      else
-        fetch_count = case limit_or_constraints
-          when Numeric then limit_or_constraints.to_i
-          when String
-            unless limit_or_constraints =~ /\A-?\d+\z/
+      # Fetch on a temporary state: the limit, constraints, and cached
+      # results set for this call never stay on the query.
+      with_temporary_query_state do
+        if limit_or_constraints.is_a?(Hash)
+          conditions(limit_or_constraints)
+          # Check if limit was set in constraints, otherwise use 1
+          # Handle :max case - if @limit is :max, default to 1 for first()
+          fetch_count = (@limit.is_a?(Numeric) ? @limit : nil) || 1
+        else
+          fetch_count = case limit_or_constraints
+            when Numeric then limit_or_constraints.to_i
+            when String
+              unless limit_or_constraints =~ /\A-?\d+\z/
+                raise ArgumentError,
+                      "Invalid first() argument #{limit_or_constraints.inspect}. " \
+                      "Expected an Integer, a numeric String, or a Hash of constraints."
+              end
+              limit_or_constraints.to_i
+            else
               raise ArgumentError,
                     "Invalid first() argument #{limit_or_constraints.inspect}. " \
                     "Expected an Integer, a numeric String, or a Hash of constraints."
             end
-            limit_or_constraints.to_i
-          else
-            raise ArgumentError,
-                  "Invalid first() argument #{limit_or_constraints.inspect}. " \
-                  "Expected an Integer, a numeric String, or a Hash of constraints."
-          end
+        end
         @results = nil if @limit != fetch_count
         @limit = fetch_count
+        # Apply any additional keyword options as conditions (e.g., keys:, includes:)
+        conditions(options) unless options.empty?
+        fetch_count == 1 ? results.first : results.first(fetch_count)
       end
-      # Apply any additional keyword options as conditions (e.g., keys:, includes:)
-      conditions(options) unless options.empty?
-      fetch_count == 1 ? results.first : results.first(fetch_count)
     end
 
     # Returns the most recently created object(s) (ordered by created_at descending).
@@ -1517,21 +2339,16 @@ module Parse
     # @return [Parse::Object] if limit == 1
     # @return [Array<Parse::Object>] if limit > 1
     # @note Supports all constraint options like :keys, :includes, :limit, etc.
+    #   The query itself is not changed: the order, limit, and constraints
+    #   apply to this call only. `createdAt` descending is the primary sort;
+    #   an existing order on other fields breaks ties.
     # @example
     #   query.latest                          # single most recent
     #   query.latest(5)                       # 5 most recent
     #   query.latest(:user.eq => x)           # most recent for user
     #   query.latest(:user.eq => x, limit: 5) # 5 most recent for user
     def latest(limit = 1, **options)
-      # Allow limit to be overridden via options
-      limit = options.delete(:limit) if options.key?(:limit)
-      @results = nil if @limit != limit
-      @limit = limit
-      # Add created_at descending order if not already present
-      order(:created_at.desc) unless @order.any? { |o| o.operand == :created_at }
-      # Apply any additional keyword options as conditions (e.g., keys:, includes:)
-      conditions(options) unless options.empty?
-      limit == 1 ? results.first : results.first(limit)
+      newest_by(:created_at, limit, **options)
     end
 
     # Returns the most recently updated object(s) (ordered by updated_at descending).
@@ -1539,21 +2356,53 @@ module Parse
     # @return [Parse::Object] if limit == 1
     # @return [Array<Parse::Object>] if limit > 1
     # @note Supports all constraint options like :keys, :includes, :limit, etc.
+    #   The query itself is not changed, as with {#latest}.
     # @example
     #   query.last_updated                          # single most recently updated
     #   query.last_updated(5)                       # 5 most recently updated
     #   query.last_updated(:user.eq => x)           # most recently updated for user
     #   query.last_updated(:user.eq => x, limit: 5) # 5 most recently updated for user
     def last_updated(limit = 1, **options)
+      newest_by(:updated_at, limit, **options)
+    end
+
+    # @!visibility private
+    # Shared body of {#latest} and {#last_updated}.
+    def newest_by(field, limit, **options)
       # Allow limit to be overridden via options
       limit = options.delete(:limit) if options.key?(:limit)
-      @results = nil if @limit != limit
-      @limit = limit
-      # Add updated_at descending order if not already present
-      order(:updated_at.desc) unless @order.any? { |o| o.operand == :updated_at }
-      # Apply any additional keyword options as conditions (e.g., keys:, includes:)
-      conditions(options) unless options.empty?
-      limit == 1 ? results.first : results.first(limit)
+      with_temporary_query_state do
+        @results = nil
+        @limit = limit
+        column = Query.format_field(field)
+        # Put the timestamp first; keep any other existing order as a
+        # tiebreaker. An existing order on the same column is replaced.
+        existing = @order.reject { |o| Query.format_field(o.field) == column }
+        @order = []
+        order(field.to_sym.desc)
+        @order.concat(existing)
+        # Apply any additional keyword options as conditions (e.g., keys:, includes:)
+        conditions(options) unless options.empty?
+        limit == 1 ? results.first : results.first(limit)
+      end
+    end
+
+    # @!visibility private
+    # Run the block, then restore every instance variable to its value from
+    # before the block (Arrays and Hashes are copied, so in-place appends
+    # are undone too). Used by the fetch helpers that adjust the limit,
+    # order, or constraints for one call.
+    def with_temporary_query_state
+      saved = instance_variables.each_with_object({}) do |ivar, memo|
+        value = instance_variable_get(ivar)
+        memo[ivar] = value.is_a?(Array) || value.is_a?(Hash) ? value.dup : value
+      end
+      begin
+        yield
+      ensure
+        (instance_variables - saved.keys).each { |ivar| remove_instance_variable(ivar) }
+        saved.each { |ivar, value| instance_variable_set(ivar, value) }
+      end
     end
 
     # Retrieve a single object by its objectId.
@@ -1584,8 +2433,10 @@ module Parse
       batch_size = 100
       results = []
       # determine if there is a user provided hard limit
+      return [] if @limit == 0
       _limit = (@limit.is_a?(Numeric) && @limit > 0) ? @limit : nil
       compiled_query[:skip] ||= 0
+      add_paging_tiebreaker!(compiled_query)
 
       loop do
         # always reset the batch size
@@ -1634,8 +2485,26 @@ module Parse
       results
     end
 
+    # @!visibility private
+    # Skip-based paging is only stable under a total order. When several rows
+    # share the sort value, the server may return them in a different order
+    # on each page request, so rows repeat on one page and are skipped on
+    # another. Ending the order with `objectId` makes every page boundary
+    # deterministic. Left alone when the query already orders by objectId, or
+    # when `$near` / `$text` supply their own relevance order.
+    # @param compiled_query [Hash] a compiled query (mutated).
+    def add_paging_tiebreaker!(compiled_query)
+      where = compiled_query[:where].to_s
+      return if where.include?("$near") || where.include?("$text")
+      order = compiled_query[:order].to_s
+      fields = order.split(",").map { |f| f.strip.delete_prefix("-") }
+      return if fields.include?("objectId") || fields.any? { |f| f.start_with?("$") }
+      compiled_query[:order] = order.empty? ? "objectId" : "#{order},objectId"
+    end
+
     # @!visibility private
     def _opts
+      enforce_or_branch_scope!
       opts = {}
       opts[:cache] = self.cache || false
       # Only forward `use_master_key` when the caller actually set it.
@@ -1645,6 +2514,14 @@ module Parse
       # init-block comment on `@use_master_key`.
       opts[:use_master_key] = self.use_master_key unless self.use_master_key.nil?
       opts[:session_token] = self.session_token unless self.session_token.nil?
+      # SDK-internal metadata read (the role-graph walk used for scope
+      # enforcement): keeps the master key inside `Parse.without_master_key`.
+      # Set only by the SDK through an instance variable, never a public option.
+      if @_metadata_master == true
+        opts[:use_master_key] = true
+        opts.delete(:session_token)
+        opts[:metadata_master] = Parse::Client::METADATA_MASTER_REQUEST
+      end
       # for now, don't cache requests where we disable master_key or provide session token
       # if opts[:use_master_key] == false || opts[:session_token].present?
       #   opts[:cache] = false
@@ -1814,6 +2691,9 @@ module Parse
     # @param mongo_direct [Boolean] if true, queries MongoDB directly bypassing Parse Server.
     #   Requires Parse::MongoDB to be configured. Default: false.
     def results(raw: false, return_pointers: false, mongo_direct: false, &block)
+      # `limit(0)` asks for no rows: answer without a request. Sending no
+      # limit would return the server default page of 100.
+      return [] if @limit == 0
       # Use direct MongoDB query if requested
       if mongo_direct
         return results_direct(raw: raw, **mongo_direct_auth_kwargs, &block)
@@ -1921,6 +2801,9 @@ module Parse
       unless use_master_key == true
         ambient = ambient_session_token
         return true if ambient.is_a?(String) && !ambient.empty?
+        # A client bound to a user's session (`become`, `session_client`,
+        # a webhook `user_client`) is scoped the same way.
+        return true if client_bound_session_token
       end
       false
     end
@@ -1984,7 +2867,7 @@ module Parse
     # @return [self]
     def scope_to_user(user)
       raise ArgumentError, "[Parse::Query] scope_to_user requires a Parse::User or User Pointer." unless user.respond_to?(:id) && user.id.is_a?(String)
-      @acl_user = user
+      guard_or_scope_change { @acl_user = user }
       self
     end
 
@@ -2024,7 +2907,7 @@ module Parse
       # Parse::ACLScope#resolve_for_role only ever sees Parse::Role or
       # String. Without normalization, any String-only operation
       # (e.g. #start_with?, #sub) silently NoMethodErrors on Symbol.
-      @acl_role = role.is_a?(Symbol) ? role.to_s : role
+      guard_or_scope_change { @acl_role = role.is_a?(Symbol) ? role.to_s : role }
       self
     end
 
@@ -2083,7 +2966,7 @@ module Parse
       # query would raise instead of running scoped — and on a master
       # client the ambient is what `mongo_direct_auth_kwargs` forwards so
       # the read is scoped rather than silently master.
-      has_ambient_session = !ambient_session_token.nil?
+      has_ambient_session = !ambient_session_token.nil? || !client_bound_session_token.nil?
       # Mirror the request-layer auth resolution in Parse::Client#request:
       # when the process is in "server mode" — Parse.client_mode == false
       # AND the resolved Parse::Client has a master_key — and the caller
@@ -2099,7 +2982,11 @@ module Parse
           false
         end
       server_mode_master = (use_master_key != false) && !Parse.client_mode && client_has_master_key
-      unless use_master_key || server_mode_master || @acl_user || @acl_role || has_session || has_ambient_session
+      # Inside `Parse.without_master_key` REST sends no master key, so
+      # neither the explicit opt-in nor the server-mode default authorizes
+      # a direct read there.
+      master_authorized = (use_master_key || server_mode_master) && !master_key_suppressed?
+      unless master_authorized || @acl_user || @acl_role || has_session || has_ambient_session
         raise MongoDirectRequired,
           "[Parse::Query] This query uses a constraint that can only run " \
           "via mongo-direct. Mongo-direct bypasses Parse Server's enforcement, " \
@@ -2166,6 +3053,10 @@ module Parse
 
     # @!visibility private
     def mongo_direct_scope_kwargs
+      enforce_or_branch_scope!
+      # SDK-internal metadata read (see `_opts`): master mode on the direct
+      # path too, whatever `Parse.without_master_key` says.
+      return { master: Parse::ACLScope::METADATA_MASTER } if @_metadata_master == true
       if @acl_user
         # Pre-resolved User pointer. Hand it to Parse::ACLScope as
         # acl_user: so the same three-layer simulation runs (top-level
@@ -2189,11 +3080,73 @@ module Parse
         # deliberate admin call and skips the ambient, exactly as the REST
         # path does.
         { session_token: ambient }
-      else
+      elsif use_master_key != true && anonymous_session_block?
+        # Inside `Parse.with_session(nil)`: REST sends neither a token nor
+        # the master key, so the direct read runs in the public scope too.
+        {}
+      elsif use_master_key != true && (bound = client_bound_session_token)
+        # The query's client carries its own session token (a client from
+        # `Parse::Client#become`, `Parse::User#session_client`, or a webhook
+        # payload's `user_client`). REST sends that token on every request
+        # from the client, so the direct read is scoped to the same user.
+        { session_token: bound }
+      elsif mongo_direct_master_posture?
         { master: true }
+      else
+        # A client with no master key, `Parse.client_mode`, or an explicit
+        # `use_master_key = false`, and no session anywhere: REST would run
+        # this read anonymously. Return no auth so Parse::ACLScope resolves
+        # the public scope (or raises ACLRequired when
+        # `require_session_token` is on) instead of reading as master.
+        {}
       end
     end
 
+    # The session token bound to this query's client, or nil.
+    # @return [String, nil]
+    # @!visibility private
+    def client_bound_session_token
+      c = begin
+          client
+        rescue StandardError
+          nil
+        end
+      return nil unless c.respond_to?(:session_token)
+      token = c.session_token
+      token = token.session_token if token.respond_to?(:session_token)
+      token.is_a?(String) && !token.strip.empty? ? token : nil
+    end
+
+    # Whether REST would send the master key for this query: the client
+    # holds one and the caller either asked for it explicitly or left the
+    # choice to the server-mode default (`Parse.client_mode` off and no
+    # `use_master_key = false`). Mirrors Parse::Client#request.
+    # @return [Boolean]
+    # @!visibility private
+    def mongo_direct_master_posture?
+      # Inside `Parse.without_master_key` this still answers true: the
+      # resulting `master: true` is dropped by Parse::ACLScope.resolve!,
+      # which runs the read in the public scope (or raises under
+      # `require_session_token`) with the block-specific message.
+      c = begin
+          client
+        rescue StandardError
+          nil
+        end
+      has_key = c.respond_to?(:master_key) && !c.master_key.to_s.empty?
+      return false unless has_key
+      return true if use_master_key == true
+      use_master_key != false && !Parse.client_mode
+    end
+
+    # @return [Boolean] true inside a `Parse.without_master_key` block (and
+    #   not re-enabled by a nested `Parse.with_master_key`), where REST sends
+    #   no master key on any request.
+    # @!visibility private
+    def master_key_suppressed?
+      Parse.respond_to?(:master_key_disabled?) && Parse.master_key_disabled?
+    end
+
     # Auth kwargs for the Atlas Search bridge (`#atlas_search` builder
     # block). Explicit `atlas_search(...)` auth kwargs win; otherwise
     # derive from the query's own scope (`#scope_to_user`, an explicit
@@ -2225,13 +3178,20 @@ module Parse
         end
 
       explicit = %i[session_token master acl_user acl_role].select { |k| options.key?(k) }
-      return client_kwarg.merge(explicit.to_h { |k| [k, options[k]] }) if explicit.any?
+      if explicit.any? || options.key?(:client)
+        given = explicit.to_h { |k| [k, options[k]] }
+        enforce_explicit_auth_against_or_scope!(client: options[:client], **given)
+      end
+      if explicit.any?
+        return client_kwarg.merge(given)
+      end
 
       client_kwarg.merge(atlas_search_scope_kwargs)
     end
 
     # @!visibility private
     def atlas_search_scope_kwargs
+      enforce_or_branch_scope!
       if @acl_user
         { acl_user: @acl_user }
       elsif @acl_role
@@ -2239,14 +3199,28 @@ module Parse
       elsif @session_token.is_a?(String) && !@session_token.empty?
         { session_token: @session_token }
       elsif use_master_key == true
+        # An explicit master request skips the ambient session, as on REST.
+        # Inside `Parse.without_master_key` Parse::AtlasSearch drops it and
+        # the search runs in the public scope.
         { master: true }
       elsif (ambient = ambient_session_token)
         { session_token: ambient }
+      elsif anonymous_session_block?
+        {}
+      elsif (bound = client_bound_session_token)
+        { session_token: bound }
       else
         {}
       end
     end
 
+    # @return [Boolean] true inside an anonymous `Parse.with_session(nil)`
+    #   block, where requests carry neither a session token nor the master key.
+    # @!visibility private
+    def anonymous_session_block?
+      Parse.respond_to?(:anonymous_session?) && Parse.anonymous_session?
+    end
+
     # The fiber-local ambient session token set by `Parse.with_session`,
     # or nil. A whitespace-only ambient is treated as absent so it cannot
     # block the master fallback and then fail a later presence check —
@@ -2259,6 +3233,18 @@ module Parse
       ambient if ambient.is_a?(String) && !ambient.strip.empty?
     end
 
+    # Like the default `inspect`, but never prints the session token, which
+    # would otherwise reach logs and error reports.
+    # @return [String]
+    def inspect
+      ivars = instance_variables.map do |ivar|
+        value = instance_variable_get(ivar)
+        shown = ivar == :@session_token && value ? "[FILTERED]" : value.inspect
+        "#{ivar}=#{shown}"
+      end
+      "#<#{self.class.name} #{ivars.join(", ")}>"
+    end
+
     # Check if this query contains constraints that require aggregation pipeline processing
     # @return [Boolean] true if aggregation pipeline is required
     def requires_aggregation_pipeline?
@@ -2318,6 +3304,11 @@ module Parse
     # @note This is a read-only operation. Direct MongoDB queries cannot modify data.
     # @see Parse::MongoDB.configure
     def results_direct(raw: false, max_time_ms: nil, session_token: nil, master: nil, acl_user: nil, acl_role: nil, client: nil, &block)
+      enforce_explicit_auth_against_or_scope!(session_token: session_token, master: master,
+                                              acl_user: acl_user, acl_role: acl_role, client: client)
+      # `limit(0)` asks for no rows. MongoDB rejects `$limit: 0`, and
+      # omitting the stage would return every row.
+      return [] if @limit == 0
       require_relative "mongodb"
       Parse::MongoDB.require_gem!
 
@@ -2463,6 +3454,8 @@ module Parse
     # @note This is a read-only operation. Direct MongoDB queries cannot modify data.
     # @see Parse::MongoDB.configure
     def count_direct(session_token: nil, master: nil, acl_user: nil, acl_role: nil, client: nil)
+      enforce_explicit_auth_against_or_scope!(session_token: session_token, master: master,
+                                              acl_user: acl_user, acl_role: acl_role, client: client)
       require_relative "mongodb"
       Parse::MongoDB.require_gem!
 
@@ -2541,6 +3534,8 @@ module Parse
     def distinct_direct(field, return_pointers: false, order: nil,
                                session_token: nil, master: nil, acl_user: nil, acl_role: nil,
                                client: nil)
+      enforce_explicit_auth_against_or_scope!(session_token: session_token, master: master,
+                                              acl_user: acl_user, acl_role: acl_role, client: client)
       require_relative "mongodb"
       Parse::MongoDB.require_gem!
 
@@ -2944,9 +3939,13 @@ module Parse
       if compiled_where.present?
         # Convert field names and values for direct MongoDB access.
         # `compiled_where` is already marker-free, so no further
-        # reject pass is required.
-        mongo_constraints = convert_constraints_for_direct_mongodb(compiled_where)
+        # reject pass is required. Subquery constraints (`$inQuery`,
+        # `$notInQuery`, `$select`, `$dontSelect`) have no MongoDB
+        # equivalent and are compiled into `$lookup` joins plus a
+        # post-join `$match`; see #direct_subquery_stages.
+        mongo_constraints, subquery_stages = direct_subquery_stages(compiled_where)
         pipeline << { "$match" => mongo_constraints } if mongo_constraints.any?
+        pipeline.concat(subquery_stages)
       end
 
       # Handle aggregation pipeline stages (from empty_or_nil, set_equals, etc.)
@@ -3001,9 +4000,23 @@ module Parse
           "_acl" => 1,
         }
         @keys.each do |key|
-          mongo_field = convert_field_for_direct_mongodb(key.to_s)
+          # A dotted key (`meta.k`, `owner.name`) selects its top-level
+          # column on REST: Parse Server keeps the whole `meta` object, or
+          # the whole `owner` pointer. Projecting the dotted path would
+          # return a partial sub-document REST never produces.
+          top = key.to_s.split(".", 2).first
+          next if top.nil? || top.empty?
+          mongo_field = convert_field_for_direct_mongodb(top)
           project_stage[mongo_field] = 1
         end
+        # Keep each include's `$lookup` output. Without it the joined
+        # document was projected away and the field decoded as a bare
+        # pointer even though the caller asked for it to be included.
+        @includes.each do |inc|
+          base = inc.to_s.split(".", 2).first
+          next if base.nil? || base.empty?
+          project_stage["_included_#{base}"] = 1 if get_pointer_target_class(base.to_sym)
+        end
         pipeline << { "$project" => project_stage }
       end
 
@@ -3058,11 +4071,16 @@ module Parse
           },
         }
 
-        # Stage 3: Unwind the array (since $lookup returns array, but we want single object)
+        # Stage 3: Collapse the `$lookup` array to its single document.
+        # An include that resolves to nothing (dangling pointer, or a row the
+        # scope cannot read, which the ACL rewriter filters out of the
+        # join) becomes an explicit null, so the row converter can drop the
+        # field the way REST does instead of leaving a bare pointer.
         stages << {
-          "$unwind" => {
-            "path" => "$#{lookup_result_field}",
-            "preserveNullAndEmptyArrays" => true,
+          "$addFields" => {
+            lookup_result_field => {
+              "$ifNull" => [{ "$arrayElemAt" => ["$#{lookup_result_field}", 0] }, nil],
+            },
           },
         }
 
@@ -3107,6 +4125,244 @@ module Parse
       end
     end
 
+    # Subquery operators the mongo-direct path compiles into `$lookup`
+    # joins. MongoDB has no equivalent; passed through verbatim they fail
+    # with "unknown operator".
+    DIRECT_SUBQUERY_OPERATORS = %w[$inQuery $notInQuery $select $dontSelect].freeze
+
+    # Logical operators whose clauses may hold subquery constraints.
+    DIRECT_LOGICAL_OPERATORS = %w[$and $or $nor].freeze
+
+    # Split compiled constraints into a MongoDB `$match` and the extra
+    # stages that implement subquery operators.
+    #
+    # * `$inQuery` / `$notInQuery`: `$lookup` the pointed-to row in the
+    #   subquery's class, filtered by the subquery's `where`, then keep rows
+    #   whose join is non-empty (or empty).
+    # * `$select` / `$dontSelect`: `$lookup` rows of the subquery's class
+    #   matching its `where` whose `key` equals this row's field, then keep
+    #   rows whose join is non-empty (or empty).
+    #
+    # A subquery inside `$and` / `$or` / `$nor` (at any depth, as
+    # `or_where` produces) gets its own `$lookup` too. The logical clause
+    # holding it moves to the post-join `$match`, with the subquery replaced
+    # by a test on its join result, so `$or` keeps its meaning. Constraints
+    # with no subquery stay in the first `$match`, ahead of the joins. A
+    # subquery in any other position (under `$not`, `$elemMatch`, `$expr`)
+    # cannot be translated and raises ArgumentError rather than reaching
+    # MongoDB as an unknown operator.
+    #
+    # The joins run through Parse::MongoDB.aggregate, so the ACL rewriter
+    # filters the joined rows by `_rperm`, the joined class's CLP is
+    # checked, and a `where` on the joined class's protectedFields is
+    # refused, as Parse Server does for its subqueries. Temporary join
+    # columns are removed with `$unset`.
+    #
+    # @param constraints [Hash] compiled where constraints.
+    # @return [Array(Hash, Array<Hash>)] the `$match` body and the stages.
+    # @raise [ArgumentError] when a subquery sits where it cannot be translated.
+    # @api private
+    def direct_subquery_stages(constraints)
+      unless direct_subquery_present?(constraints)
+        return [convert_constraints_for_direct_mongodb(constraints), []]
+      end
+
+      plain = {}
+      post = {}
+      lookups = []
+      temps = []
+      constraints.each do |field, value|
+        direct_translate_subquery_pair(field, value, plain, post, lookups, temps)
+      end
+      match = convert_constraints_for_direct_mongodb(plain)
+      refuse_untranslated_subquery!(match)
+      refuse_untranslated_subquery!(post)
+
+      stages = lookups
+      stages << { "$match" => post } if post.any?
+      stages << { "$unset" => temps } if temps.any?
+      [match, stages]
+    end
+
+    # Translate one `field => value` constraint. A constraint with no
+    # subquery is collected into `plain` unchanged (converted later by the
+    # caller). A subquery operator adds a `$lookup` to `lookups` and a test
+    # on its join result to `out`. A logical operator holding a subquery is
+    # rebuilt clause by clause into `out`.
+    # @api private
+    def direct_translate_subquery_pair(field, value, plain, out, lookups, temps)
+      key = field.to_s
+      if DIRECT_LOGICAL_OPERATORS.include?(key) && value.is_a?(Array)
+        if direct_subquery_present?(value)
+          direct_merge_clause!(out, key, value.map { |clause| direct_translate_subquery_clause(clause, lookups, temps) })
+        else
+          plain[field] = value
+        end
+        return
+      end
+
+      ops = value.is_a?(Hash) ? value.keys.map(&:to_s) & DIRECT_SUBQUERY_OPERATORS : []
+      if ops.empty?
+        plain[field] = value
+        return
+      end
+      others = value.reject { |k, _| DIRECT_SUBQUERY_OPERATORS.include?(k.to_s) }
+      plain[field] = others if others.any?
+      ops.each do |op|
+        spec = value.key?(op) ? value[op] : value[op.to_sym]
+        temp = "_subquery_#{temps.size}_#{key.gsub(/[^A-Za-z0-9_]/, "_")}"
+        temps << temp
+        lookups << direct_subquery_lookup(key, op, spec, temp)
+        out[temp] = %w[$inQuery $select].include?(op) ? { "$ne" => [] } : { "$eq" => [] }
+      end
+    end
+
+    # Translate one clause of a logical operator into a MongoDB filter
+    # that reads the join results.
+    # @api private
+    def direct_translate_subquery_clause(clause, lookups, temps)
+      unless clause.is_a?(Hash)
+        raise ArgumentError,
+              "[Parse::Query] a logical operator clause holding a subquery must be a Hash, got #{clause.class}."
+      end
+      plain = {}
+      out = {}
+      clause.each do |field, value|
+        direct_translate_subquery_pair(field, value, plain, out, lookups, temps)
+      end
+      converted = convert_constraints_for_direct_mongodb(plain)
+      return converted.merge(out) if (converted.keys & out.keys).empty?
+      # The same operator appeared twice (a String and a Symbol key).
+      # Keep both by matching them together rather than letting one
+      # overwrite the other.
+      { "$and" => [converted, out] }
+    end
+
+    # Add a translated logical clause to `out` without overwriting one that
+    # is already there under the same operator.
+    # @api private
+    def direct_merge_clause!(out, key, clauses)
+      if out.key?(key)
+        existing = out.delete(key)
+        out["$and"] = Array(out.delete("$and")) + [{ key => existing }, { key => clauses }]
+      else
+        out[key] = clauses
+      end
+    end
+
+    # Fail closed when a subquery operator is still present after
+    # translation. MongoDB has no such operator, and a subquery in a
+    # position the SDK cannot join (under `$not`, `$elemMatch`, `$expr`)
+    # must not run as some other filter.
+    # @raise [ArgumentError]
+    # @api private
+    def refuse_untranslated_subquery!(node, context: :direct)
+      case node
+      when Hash
+        node.each do |key, value|
+          if DIRECT_SUBQUERY_OPERATORS.include?(key.to_s)
+            if context == :aggregate
+              raise ArgumentError,
+                    "[Parse::Query] #{key} cannot be translated into an aggregation pipeline in " \
+                    "this position. Aggregations translate only top-level $inQuery / $notInQuery " \
+                    "field constraints into joins. Use results_direct / count_direct, which also " \
+                    "translate subqueries inside $and / $or / $nor, or run the query via REST."
+            end
+            raise ArgumentError,
+                  "[Parse::Query] #{key} cannot run on the mongo-direct path in this position. " \
+                  "A subquery is translated into a join only as a field constraint, at the top " \
+                  "level or inside $and / $or / $nor. Run this query via REST, or move the " \
+                  "subquery out of the enclosing operator."
+          end
+          refuse_untranslated_subquery!(value, context: context)
+        end
+      when Array
+        node.each { |child| refuse_untranslated_subquery!(child, context: context) }
+      end
+      nil
+    end
+
+    # @return [Boolean] true when a subquery operator appears anywhere in
+    #   the constraints, at any depth.
+    # @api private
+    def direct_subquery_present?(constraints)
+      case constraints
+      when Hash
+        constraints.any? do |key, value|
+          DIRECT_SUBQUERY_OPERATORS.include?(key.to_s) || direct_subquery_present?(value)
+        end
+      when Array
+        constraints.any? { |child| direct_subquery_present?(child) }
+      else
+        false
+      end
+    end
+
+    # Build the `$lookup` stage for one subquery operator.
+    # @api private
+    def direct_subquery_lookup(field, op, spec, temp)
+      spec = (spec || {}).transform_keys(&:to_s)
+      if op == "$select" || op == "$dontSelect"
+        query = (spec["query"] || {})
+        query = query.transform_keys(&:to_s) if query.is_a?(Hash)
+        class_name = query["className"].to_s
+        where = query["where"] || {}
+        key = (spec["key"] || field).to_s
+      else
+        class_name = spec["className"].to_s
+        where = spec["where"] || {}
+        key = nil
+      end
+      if class_name.empty?
+        raise ArgumentError, "[Parse::Query] #{op} on '#{field}' is missing the subquery className."
+      end
+
+      sub = Parse::Query.new(class_name)
+      sub_match, sub_stages = Parse::Query.with_field_aliases(class_name) do
+        sub.send(:direct_subquery_stages, where.is_a?(Hash) ? where : {})
+      end
+      local = convert_field_for_direct_mongodb(field)
+
+      if key.nil?
+        # `$inQuery` / `$notInQuery` compare a pointer column, stored as
+        # `Class$objectId`, with the subquery row's `_id`.
+        local = "_p_#{Query.format_field(field)}" unless local.start_with?("_p_")
+        pipeline = [
+          { "$match" => { "$expr" => { "$eq" => ["$_id", "$$subquery_id"] } } },
+        ]
+        pipeline << { "$match" => sub_match } if sub_match.any?
+        pipeline.concat(sub_stages)
+        pipeline << { "$limit" => 1 }
+        {
+          "$lookup" => {
+            "from" => class_name,
+            "let" => {
+              "subquery_id" => {
+                "$arrayElemAt" => [{ "$split" => ["$#{local}", { "$literal" => "$" }] }, 1],
+              },
+            },
+            "pipeline" => pipeline,
+            "as" => temp,
+          },
+        }
+      else
+        foreign = Parse::Query.with_field_aliases(class_name) { sub.send(:convert_field_for_direct_mongodb, key) }
+        pipeline = []
+        pipeline << { "$match" => sub_match } if sub_match.any?
+        pipeline.concat(sub_stages)
+        pipeline << { "$match" => { "$expr" => { "$eq" => ["$#{foreign}", "$$subquery_value"] } } }
+        pipeline << { "$limit" => 1 }
+        {
+          "$lookup" => {
+            "from" => class_name,
+            "let" => { "subquery_value" => "$#{local}" },
+            "pipeline" => pipeline,
+            "as" => temp,
+          },
+        }
+      end
+    end
+
     # Convert constraints for direct MongoDB execution.
     # @param constraints [Hash] the compiled where constraints
     # @return [Hash] constraints with MongoDB-native field names
@@ -3151,6 +4407,12 @@ module Parse
 
         # Convert field name for MongoDB
         mongo_field = convert_field_for_direct_mongodb(field_str)
+        # Bare objectIds against a pointer column use the storage form.
+        value = coerce_bare_pointer_ids(field_str, value, arrays: true)
+        # `$containedBy` (every array element is in the list) has no MongoDB
+        # operator. Parse Server's equivalent is "no element outside the
+        # list".
+        value = rewrite_contained_by_for_direct(value)
 
         # Convert value
         result[mongo_field] = convert_value_for_direct_mongodb(field_str, value)
@@ -3159,6 +4421,16 @@ module Parse
       result
     end
 
+    # @api private
+    def rewrite_contained_by_for_direct(value)
+      return value unless value.is_a?(Hash)
+      key = value.key?("$containedBy") ? "$containedBy" : (value.key?(:$containedBy) ? :$containedBy : nil)
+      return value if key.nil?
+      list = value[key]
+      rest = value.reject { |k, _| k == key }
+      rest.merge("$not" => { "$elemMatch" => { "$nin" => Array(list) } })
+    end
+
     # Convert a field name for direct MongoDB access.
     # @param field [String] the Parse field name
     # @return [String] the MongoDB field name
@@ -3561,11 +4833,11 @@ module Parse
       lq_client = client || Parse::LiveQuery.client
       lq_client.subscribe(
         @table,
-        where: compile_where,
+        where: compile_rest_where,
         fields: fields,
         keys: keys,
         watch: watch,
-        session_token: session_token || @session_token,
+        session_token: live_query_session_token(session_token, live_query_client: lq_client),
         use_master_key: use_master_key,
         &block
       )
@@ -3667,7 +4939,8 @@ module Parse
     #   at the top-level stage.
     BLOCKED_PIPELINE_STAGES = Parse::PipelineSecurity::DENIED_OPERATORS
 
-    def aggregate(pipeline, verbose: nil, mongo_direct: nil, rewrite_lookups: nil, raw_values: false, raw_field_names: false)
+    def aggregate(pipeline, verbose: nil, mongo_direct: nil, rewrite_lookups: nil, raw_values: false, raw_field_names: false,
+                  window_before_pipeline: false)
       validate_pipeline!(pipeline)
 
       # Auto-rewrite LLM-style $lookup stages against logical Parse class
@@ -3767,29 +5040,31 @@ module Parse
         end
       end
 
-      # Append the provided pipeline stages
-      complete_pipeline.concat(pipeline)
+      if window_before_pipeline
+        # The query's order / skip / limit select the rows the pipeline
+        # (a `$group` from sum, average, group_by, ...) runs over. Leading
+        # `$match` stages of the pipeline filter rows, so they run first.
+        leading = pipeline.take_while { |stage| stage.is_a?(Hash) && stage.keys == ["$match"] }
+        complete_pipeline.concat(leading)
+        complete_pipeline.concat(query_window_stages)
+        complete_pipeline.concat(pipeline.drop(leading.size))
+      else
+        # Append the provided pipeline stages
+        complete_pipeline.concat(pipeline)
 
-      # Add $sort stage from order constraints if any exist
-      unless @order.empty?
-        sort_stage = {}
-        @order.each do |order_obj|
-          # order_obj is a Parse::Order object with field and direction
-          field_name = order_obj.field.to_s
-          direction = order_obj.direction == :desc ? -1 : 1
-          sort_stage[field_name] = direction
-        end
-        complete_pipeline << { "$sort" => sort_stage } if sort_stage.any?
-      end
+        # Add $sort stage from order constraints if any exist
+        sort = query_sort_stage
+        complete_pipeline << sort if sort
 
-      # Add $skip stage if specified
-      if @skip > 0
-        complete_pipeline << { "$skip" => @skip }
-      end
+        # Add $skip stage if specified
+        if @skip > 0
+          complete_pipeline << { "$skip" => @skip }
+        end
 
-      # Add $limit stage if specified
-      if @limit.is_a?(Numeric) && @limit > 0
-        complete_pipeline << { "$limit" => @limit }
+        # Add $limit stage if specified
+        if @limit.is_a?(Numeric) && @limit > 0
+          complete_pipeline << { "$limit" => @limit }
+        end
       end
 
       # Optimize pipeline by merging consecutive $match stages
@@ -3861,6 +5136,35 @@ module Parse
                                                raw_values: raw_values, raw_field_names: raw_field_names)
     end
 
+    # @!visibility private
+    # The `$sort` stage for the query's order, or nil.
+    # @return [Hash, nil]
+    def query_sort_stage
+      return nil if @order.empty?
+      sort_stage = {}
+      @order.each do |order_obj|
+        sort_stage[order_obj.field.to_s] = order_obj.direction == :desc ? -1 : 1
+      end
+      sort_stage.any? ? { "$sort" => sort_stage } : nil
+    end
+
+    # @!visibility private
+    # The stages that select which rows an aggregate helper groups: the
+    # query's order, skip, and limit, in that order. Empty unless a skip or
+    # a limit is set (an order alone does not change which rows are
+    # grouped).
+    # @return [Array<Hash>]
+    def query_window_stages
+      limited = @limit.is_a?(Numeric) && @limit > 0
+      return [] unless @skip > 0 || limited
+      stages = []
+      sort = query_sort_stage
+      stages << sort if sort
+      stages << { "$skip" => @skip } if @skip > 0
+      stages << { "$limit" => @limit } if limited
+      stages
+    end
+
     # Apply the direct-MongoDB stage converter to every stage in a pipeline.
     # Idempotent on already-translated input (the per-stage converter
     # passes `_p_*` references through unchanged).
@@ -4344,21 +5648,17 @@ module Parse
             # $notInQuery: keep documents where lookup found no matches
             post_lookup_match[lookup_result_field] = { "$eq" => [] }
           end
-        elsif value.is_a?(Hash)
-          # Recursively handle nested constraints
-          nested = extract_subquery_to_lookup_stages(value)
-          if nested[:lookup_stages].any?
-            lookup_stages.concat(nested[:lookup_stages])
-            post_lookup_match.merge!(nested[:post_lookup_match])
-            remaining_constraints[field] = nested[:constraints]
-          else
-            remaining_constraints[field] = value
-          end
         else
+          # A subquery nested anywhere else (under `$or` / `$and` / `$nor`,
+          # `$not`, `$elemMatch`) is not translated on this path. Lifting it
+          # into the post-join `$match` would drop the enclosing operator and
+          # change the query's meaning, and leaving it in place hands MongoDB
+          # an operator it does not have. The scan below refuses it.
           remaining_constraints[field] = value
         end
       end
 
+      refuse_untranslated_subquery!(remaining_constraints, context: :aggregate)
       { constraints: remaining_constraints, lookup_stages: lookup_stages, post_lookup_match: post_lookup_match }
     end
 
@@ -4390,18 +5690,11 @@ module Parse
     # @return [Boolean] true if subquery constraints are present
     def has_subquery_constraints?(constraints)
       return false unless constraints.is_a?(Hash)
-
-      constraints.any? do |field, value|
-        if value.is_a?(Hash)
-          # Check for both string and symbol keys since constraints can come from
-          # different sources (JSON parsing vs Ruby symbol keys)
-          value.key?("$inQuery") || value.key?(:"$inQuery") ||
-          value.key?("$notInQuery") || value.key?(:"$notInQuery") ||
-          has_subquery_constraints?(value)
-        else
-          false
-        end
-      end
+      # Any subquery operator at any depth (string or symbol keys, inside
+      # logical-operator arrays too), so a nested one reaches
+      # {#extract_subquery_to_lookup_stages} and is refused there rather
+      # than passed to MongoDB verbatim.
+      direct_subquery_present?(constraints)
     end
 
     alias_method :result, :results
@@ -4430,7 +5723,12 @@ module Parse
       # Keys like ["project.name", "project.status"] define which subfields to fetch on nested objects
       nested_keys = Parse::Query.parse_keys_to_nested_keys(@keys) if @keys.present?
 
-      list.map { |m| Parse::Object.build(m, @table, fetched_keys: fetch_keys, nested_fetched_keys: nested_keys) }.compact
+      built = list.map { |m| Parse::Object.build(m, @table, fetched_keys: fetch_keys, nested_fetched_keys: nested_keys) }.compact
+      # Record session owners against the client that fetched them, so a
+      # later delete of an already-gone session can still drop its owner's
+      # cached identities.
+      Parse::Session._remember_owners!(built, client) if @table == Parse::Model::CLASS_SESSION && defined?(Parse::Session)
+      built
     end
 
     # Validates includes against keys and field types, printing debug warnings for:
@@ -4570,7 +5868,9 @@ module Parse
 
       run_callbacks :prepare do
         q = {} #query
-        q[:limit] = @limit if @limit.is_a?(Numeric) && @limit > 0
+        # An explicit `limit(0)` is sent as 0 (no rows). Omitting it would let
+        # the server apply its default page size.
+        q[:limit] = @limit if @limit.is_a?(Numeric) && @limit >= 0
         q[:skip] = @skip if @skip > 0
 
         q[:include] = @includes.join(",") unless @includes.empty?
@@ -4578,7 +5878,7 @@ module Parse
         q[:excludeKeys] = @exclude_keys.join(",") if encode && @exclude_keys&.any?
         q[:order] = @order.join(",") unless @order.empty?
         unless @where.empty?
-          q[:where] = Parse::Query.compile_where(@where)
+          q[:where] = coerce_rest_pointer_ids(Parse::Query.compile_where(@where))
           q[:where] = q[:where].to_json if encode
         end
 
@@ -4611,6 +5911,94 @@ module Parse
       self.class.compile_where(@where || [])
     end
 
+    # @return [Hash] the where clause as sent to Parse Server over REST or
+    #   LiveQuery: {#compile_where} with bare objectIds on declared pointer
+    #   fields rewritten into Pointer hashes, so they match the stored
+    #   pointer.
+    def compile_rest_where
+      refuse_pipeline_only!("a LiveQuery subscription or push target")
+      coerce_rest_pointer_ids(compile_where)
+    end
+
+    # @!visibility private
+    # Compile this query as a subquery of another (`$inQuery`,
+    # `$notInQuery`, `$select`, `$dontSelect`). Parse Server evaluates it
+    # from the REST form, so a pipeline-only constraint, which that form
+    # drops, is refused rather than turning the subquery into match-all.
+    # @return [Hash]
+    def compile_subquery
+      refuse_pipeline_only!("a subquery")
+      enforce_or_branch_scope!
+      compile(encode: false, includeClassName: true)
+    end
+
+    # @!visibility private
+    # Raise when this query holds a constraint that only the aggregation
+    # pipeline or mongo-direct can run, for a target that receives only
+    # the REST where form.
+    def refuse_pipeline_only!(target)
+      markers = compile_markers
+      return unless Parse::Query.or_branch_marker?(markers)
+      names = Parse::Query.pipeline_only_constraint_names(@where)
+      raise ArgumentError,
+            "This query cannot be used as #{target}: " \
+            "#{names.empty? ? "a pipeline-only constraint" : names.join(", ")} needs the aggregation " \
+            "pipeline or mongo-direct, and Parse Server receives only the REST where form, " \
+            "which would drop it."
+    end
+    private :refuse_pipeline_only!
+
+    # @!visibility private
+    # The session a LiveQuery subscription built from this query must use:
+    # the query's own session token or the session of its `become` client.
+    # LiveQuery has no equivalent of `scope_to_user` / `scope_to_role`, so
+    # those raise, and an explicit token that differs from the query's
+    # authority raises too.
+    #
+    # A query that carries any authority must target the same Parse
+    # application as the LiveQuery client, compared by application id, so
+    # one app's session token is never sent to another app's LiveQuery
+    # server. A query with the default authority sends no query-derived
+    # credential, so it is not checked.
+    # @param explicit [String, nil] a `session_token:` passed by the caller.
+    # @param live_query_client [Parse::LiveQuery::Client, nil] the client
+    #   the subscription will be sent on.
+    # @return [String, nil]
+    def live_query_session_token(explicit = nil, live_query_client: nil)
+      enforce_or_branch_scope!
+      scope = or_effective_scope
+      if scope.key?(:user) || scope.key?(:role)
+        raise ArgumentError,
+              "A query scoped with scope_to_user / scope_to_role cannot be subscribed to: " \
+              "LiveQuery authorizes by session token only. Subscribe with that user's session instead."
+      end
+      explicit = explicit.session_token if explicit.respond_to?(:session_token)
+      own = scope[:session]
+      if explicit.is_a?(String) && !explicit.empty? && own && explicit != own
+        raise ArgumentError,
+              "The session_token: passed to subscribe differs from the session this query runs under."
+      end
+      ensure_live_query_application!(live_query_client) unless scope.empty?
+      (explicit.is_a?(String) && !explicit.empty?) ? explicit : own
+    end
+
+    # @!visibility private
+    # Raise when a LiveQuery client targets a different Parse application
+    # than this query, so a credential bound to one app never reaches
+    # another. Compared by application id: the LiveQuery URL is a WebSocket
+    # endpoint and never matches the REST server URL.
+    def ensure_live_query_application!(live_query_client)
+      return if live_query_client.nil? || !live_query_client.respond_to?(:application_id)
+      query_app = or_application_identity&.first
+      lq_app = live_query_client.application_id.to_s
+      return if query_app.nil? || query_app.empty? || lq_app.empty? || query_app == lq_app
+      raise ArgumentError,
+            "This query runs under an authority bound to application #{query_app.inspect}, but the " \
+            "LiveQuery client targets #{lq_app.inspect}. Its credentials are not sent to another " \
+            "application; subscribe on a LiveQuery client for the same application."
+    end
+    private :ensure_live_query_application!
+
     # @return [Hash] the un-stripped reduced where hash, including any
     #   SDK-internal markers like `"__mongo_direct_only"` and
     #   `"__aggregation_pipeline"`. Used by the routing layer to decide
@@ -5322,6 +6710,8 @@ module Parse
     # @param result_key [String] the key to extract from the result
     # @return [Object] the aggregation result
     def execute_basic_aggregation(pipeline, operation, field, result_key)
+      # `limit(0)` selects no rows.
+      return nil if @limit == 0
       # Add match stage if there are where conditions
       compiled_where = compile_where
       if compiled_where.present?
@@ -5331,8 +6721,9 @@ module Parse
         pipeline.unshift({ "$match" => stringified_where })
       end
 
-      # Use the Aggregation class to execute
-      aggregation = aggregate(pipeline, verbose: @verbose_aggregate)
+      # Use the Aggregation class to execute. The query's order / skip /
+      # limit pick the rows before `$group`.
+      aggregation = aggregate(pipeline, verbose: @verbose_aggregate, window_before_pipeline: true)
       raw_results = aggregation.raw
 
       # Extract the result from the response
@@ -5360,7 +6751,7 @@ module Parse
           formatted = Query.format_field(field)
           # For pointer fields, MongoDB stores them with _p_ prefix
           # Check if this field is defined as a pointer in the Parse class
-          parse_class = Parse::Model.const_get(@table) rescue nil
+          parse_class = table_model_class
           if parse_class && is_pointer_field?(parse_class, field, formatted)
             "_p_#{formatted}"
           else
@@ -5410,6 +6801,94 @@ module Parse
       nil
     end
 
+    # @!visibility private
+    # Rewrite bare objectId strings compared to a pointer column into the
+    # "Class$objectId" storage form, for the aggregate and mongo-direct
+    # paths. Only applies when the column is a declared pointer with a known
+    # target class; values already in storage form, pointer hashes, and
+    # non-string values are left alone.
+    #
+    # @param field [String, Symbol] the constraint key.
+    # @param value [Object] the compiled constraint value.
+    # @param arrays [Boolean] also rewrite `$in` / `$nin` / `$all` arrays.
+    # @return [Object] the value, rewritten when it applies.
+    def coerce_bare_pointer_ids(field, value, arrays:)
+      return value unless value.is_a?(String) || value.is_a?(Hash)
+      name = field.to_s
+      name = name.delete_prefix("_p_")
+      return value if name.include?(".")
+      klass = table_model_class
+      return value unless klass
+      target = get_pointer_target_class_for(klass, name)
+      return value unless target
+      bare = ->(v) { v.is_a?(String) && !v.empty? && !v.include?("$") }
+      to_storage = ->(v) { bare.(v) ? "#{target}$#{v}" : v }
+      case value
+      when String
+        to_storage.(value)
+      when Hash
+        return value if value.key?("__type") || value.key?(:__type)
+        value.each_with_object({}) do |(op, op_value), out|
+          out[op] = case op.to_s
+            when "$eq", "$ne" then to_storage.(op_value)
+            when "$in", "$nin", "$all"
+              arrays && op_value.is_a?(Array) ? op_value.map(&to_storage) : op_value
+            else op_value
+            end
+        end
+      end
+    end
+
+    # @!visibility private
+    # Rewrite bare objectId strings compared to a declared pointer column
+    # into Pointer hashes, for the REST where clause. Parse Server compares
+    # a pointer column against its "Class$objectId" storage form, so a bare
+    # objectId never matched (and `$ne` matched every row). Same rules as
+    # {#coerce_bare_pointer_ids}: only declared pointers with a known target
+    # class, only `$eq` / `$ne` / `$in` / `$nin` / `$all` and plain
+    # equality, recursing into `$or` / `$and` / `$nor`.
+    # @param where [Hash] a compiled where clause.
+    # @return [Hash]
+    def coerce_rest_pointer_ids(where)
+      return where unless where.is_a?(Hash) && !where.empty?
+      klass = table_model_class
+      return where unless klass
+      where.each_with_object({}) do |(field, value), out|
+        name = field.to_s
+        out[field] = if %w[$or $and $nor].include?(name) && value.is_a?(Array)
+            value.map { |branch| coerce_rest_pointer_ids(branch) }
+          elsif name.start_with?("$") || name.include?(".")
+            value
+          elsif (target = get_pointer_target_class_for(klass, name))
+            rest_pointer_value(target, value)
+          else
+            value
+          end
+      end
+    end
+
+    # @!visibility private
+    def rest_pointer_value(target, value)
+      bare = ->(v) { v.is_a?(String) && !v.empty? && !v.include?("$") }
+      to_pointer = ->(v) { bare.(v) ? { "__type" => "Pointer", "className" => target, "objectId" => v } : v }
+      case value
+      when String
+        to_pointer.(value)
+      when Hash
+        return value if value.key?("__type") || value.key?(:__type)
+        value.each_with_object({}) do |(op, op_value), out|
+          out[op] = case op.to_s
+            when "$eq", "$ne" then to_pointer.(op_value)
+            when "$in", "$nin", "$all"
+              op_value.is_a?(Array) ? op_value.map(&to_pointer) : op_value
+            else op_value
+            end
+        end
+      else
+        value
+      end
+    end
+
     # Handle a constraint value that is a bare String inside `$in`/`$nin`
     # against a column positively identified as a pointer, when the
     # target class cannot be resolved (no local belongs_to AND no peer
@@ -5444,10 +6923,27 @@ module Parse
 
     # Check if a field is a pointer field using schema information
     # @param field [Symbol, String] the field name to check
+    # @api private
+    # The model class registered for this query's table. Resolves through
+    # each model's `parse_class` (Parse::Model.find_class), so it works for
+    # Parse class names that are not valid Ruby constants (`"contacts"`,
+    # `"_User"`) and for models whose `parse_class` differs from the Ruby
+    # class name. Falls back to a constant lookup for a table named after a
+    # Ruby class that has not been registered under that name. Before 5.8
+    # the query layer used `Parse::Model.const_get(@table)` alone, which
+    # raised (and was rescued to nil) for such names, so pointer fields were
+    # silently treated as plain fields: mongo-direct pipelines addressed
+    # `owner` instead of `_p_owner` and matched nothing.
+    #
+    # @return [Class, nil]
+    def table_model_class
+      Parse::Model.find_class(@table) || (Parse::Model.const_get(@table) rescue nil)
+    end
+
     # @return [Boolean] true if the field is a pointer field
     def field_is_pointer?(field)
       begin
-        parse_class = Parse::Model.const_get(@table)
+        parse_class = table_model_class
         return false unless parse_class.respond_to?(:fields)
 
         # If the field already has _p_ prefix, strip it to get the original field name
@@ -5500,7 +6996,7 @@ module Parse
     # @api private
     def field_is_known_to_schema?(field)
       begin
-        parse_class = Parse::Model.const_get(@table)
+        parse_class = table_model_class
         return false unless parse_class.respond_to?(:fields)
 
         fields_to_check = [field.to_s, field.to_sym]
@@ -5555,7 +7051,7 @@ module Parse
     def convert_pointer_value_with_schema(value, field_name, **options)
       return value unless value # nil/empty values pass through
 
-      parse_class = Parse::Model.const_get(@table) rescue nil
+      parse_class = table_model_class
       is_pointer = parse_class && is_pointer_field?(parse_class, field_name, Query.format_field(field_name))
       target_class = parse_class ? get_pointer_target_class_for(parse_class, field_name) : nil
 
@@ -5649,6 +7145,12 @@ module Parse
           next
         end
 
+        # A bare objectId compared to a pointer column becomes the
+        # "Class$objectId" storage form. Compared as-is it never equals the
+        # stored value, so equality matched nothing and `$ne` matched every
+        # row. (`$in` / `$nin` arrays are converted below.)
+        value = coerce_bare_pointer_ids(field, value, arrays: false)
+
         # Convert field name to aggregation format
         # If field already has _p_ prefix, don't reformat it
         if field.to_s.start_with?("_p_")
@@ -5696,7 +7198,7 @@ module Parse
                   class_name = nil
 
                   # First try to get it from the schema
-                  parse_class = Parse::Model.const_get(@table) rescue nil
+                  parse_class = table_model_class
                   if parse_class
                     class_name = get_pointer_target_class_for(parse_class, field)
                   end
@@ -5790,20 +7292,25 @@ module Parse
         raise ArgumentError, "All queries passed to Parse::Query.or must be for the same Parse class."
       end
 
-      # Start with an empty query for this table
+      # Start with an empty query for this table, carrying the members'
+      # common auth scope (raises when two members set different scopes).
       result = self.new(table)
+      # Run against the members' application: seed the client from the
+      # first member that sets one (the members are then checked to agree).
+      seed = queries.lazy.map { |q| q.send(:or_application_client) }.find(&:itself)
+      result.instance_variable_set(:@client, seed) if seed
+      queries.each { |query| result.send(:merge_or_scope!, query) }
 
-      # Filter to only queries that have constraints
-      queries = queries.filter { |q| q.where.present? && !q.where.empty? }
+      # Refuse pipeline-only constraints in any member first, so one is
+      # never dropped or widened.
+      queries.each { |query| compile_or_branch(query.where) }
+
+      # A query with no constraints matches every row, so an OR that
+      # includes one does too.
+      return result if queries.any? { |q| match_all?(q.where) }
 
       # Add each query's complete constraint set as an OR branch
-      queries.each do |query|
-        # Compile the where constraints to check if they result in empty conditions
-        compiled_where = Parse::Query.compile_where(query.where)
-        unless compiled_where.empty?
-          result.or_where(query.where)
-        end
-      end
+      queries.each { |query| result.or_where(query.where) }
 
       result
     end
@@ -5850,13 +7357,19 @@ module Parse
 
     # Creates a deep copy of this query object, allowing independent modifications
     # @return [Parse::Query] a new query object with the same constraints
-    # @note The @client and @results instance variables are intentionally NOT cloned.
-    #   The cloned query will use the default client when executed.
+    # @note The @results instance variable is not cloned. A client that sets
+    #   the query's authority (session-bound or without a master key) is kept
+    #   by reference; otherwise the copy uses the default client.
     def clone
       cloned_query = Parse::Query.new(self.instance_variable_get(:@table))
       # Note: :client is intentionally excluded - it contains non-serializable objects
       # (Redis connections, Faraday connections) and should be obtained lazily
-      [:count, :where, :order, :keys, :exclude_keys, :includes, :limit, :skip, :cache, :use_master_key, :hint].each do |param|
+      # The auth scope and read routing travel with the copy, so a cloned or
+      # combined query never runs under a broader authority than the
+      # original.
+      [:count, :where, :order, :keys, :exclude_keys, :includes, :limit, :skip, :cache, :use_master_key, :hint,
+       :session_token, :acl_user, :acl_role, :read_preference, :key, :acl_query_mongo_direct,
+       :_or_branch_scope, :_or_branch_app].each do |param|
         if instance_variable_defined?(:"@#{param}")
           value = instance_variable_get(:"@#{param}")
           if value.is_a?(Array) || value.is_a?(Hash)
@@ -5874,6 +7387,12 @@ module Parse
           cloned_query.instance_variable_set(:"@#{param}", cloned_value)
         end
       end
+      # A client set on the query (one from Parse::Client#become or
+      # #anonymous, or a client for another application) decides where the
+      # query's session token and authority are sent, so the copy keeps it.
+      # Only the memoized default client is resolved lazily again.
+      own_client = or_application_client
+      cloned_query.instance_variable_set(:@client, own_client) if own_client
       cloned_query.instance_variable_set(:@results, nil)
       cloned_query
     end
@@ -6111,20 +7630,62 @@ module Parse
 
   # Wrapper class for custom aggregation results (from $group, $project, etc.)
   # Provides both hash-style access and method-style access to fields.
-  # Field names are automatically converted from camelCase to snake_case.
+  #
+  # Two naming modes:
+  #
+  # * `:default` (the default): field names are converted from camelCase to
+  #   snake_case symbols. `#to_h` returns those symbol keys, and the original
+  #   string keys stay readable through `#[]` and `#raw`.
+  # * `:server`: field names are kept exactly as the aggregation returned
+  #   them. `#to_h` and `#keys` use the original String keys (`"totalPlays"`,
+  #   `"ExternalID"`), nested values are untouched, and distinct keys whose
+  #   snake_case forms collide (`"totalPlays"` and `"total_plays"`) both
+  #   survive. Method-style access still accepts a snake_case name when it
+  #   identifies exactly one key, and raises when it is ambiguous.
   #
   # @example
   #   result = AggregationResult.new({ "_id" => "Rock", "totalPlays" => 500 })
   #   result["_id"]        # => "Rock"
   #   result[:total_plays] # => 500
   #   result.total_plays   # => 500
+  #   result.to_h          # => { _id: "Rock", total_plays: 500 }
+  #
+  #   server = AggregationResult.new({ "_id" => "Rock", "totalPlays" => 500 }, field_names: :server)
+  #   server.to_h          # => { "_id" => "Rock", "totalPlays" => 500 }
   #
   class AggregationResult
+    # Naming modes accepted by `field_names:` across the SDK's result APIs.
+    FIELD_NAME_MODES = %i[default server].freeze
+
+    # Normalize a `field_names:` option. nil means `:default`.
+    #
+    # @param value [Symbol, String, nil]
+    # @return [Symbol] `:default` or `:server`
+    # @raise [ArgumentError] for any other value.
+    def self.normalize_field_names!(value)
+      return :default if value.nil?
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+      return mode if FIELD_NAME_MODES.include?(mode)
+      raise ArgumentError,
+            "field_names: must be one of #{FIELD_NAME_MODES.inspect} (got #{value.inspect})."
+    end
+
+    # @return [Symbol] `:default` or `:server`.
+    attr_reader :field_names
+
     # @param data [Hash] the raw aggregation result hash
-    def initialize(data)
+    # @param field_names [Symbol, nil] `:default` (snake_case symbol keys) or
+    #   `:server` (keys exactly as returned).
+    def initialize(data, field_names: nil)
+      @field_names = self.class.normalize_field_names!(field_names)
       @data = {}
       @raw_data = data
 
+      if @field_names == :server
+        data.each { |key, value| @data[key.to_s] = value }
+        return
+      end
+
       # Convert keys to snake_case and store
       data.each do |key, value|
         snake_key = Parse::Query.to_snake_case(key.to_s)
@@ -6137,6 +7698,7 @@ module Parse
     # @param key [String, Symbol] the field name
     # @return [Object] the field value
     def [](key)
+      return @data[server_key_for(key)] if server?
       @data[key.to_s] || @data[key.to_sym]
     end
 
@@ -6144,18 +7706,23 @@ module Parse
     # @param key [String, Symbol] the field name
     # @return [Boolean]
     def key?(key)
+      return @data.key?(server_key_for(key)) if server?
       @data.key?(key.to_s) || @data.key?(key.to_sym)
     end
 
-    # Get all keys (snake_case symbols)
-    # @return [Array<Symbol>]
+    # Get all keys: snake_case symbols by default, or the original String
+    # keys in `:server` mode.
+    # @return [Array<Symbol>, Array<String>]
     def keys
+      return @data.keys if server?
       @data.keys.select { |k| k.is_a?(Symbol) }
     end
 
-    # Convert to hash with snake_case symbol keys
+    # Convert to hash: snake_case symbol keys by default, or the original
+    # String keys (a copy, nested values untouched) in `:server` mode.
     # @return [Hash]
     def to_h
+      return @data.dup if server?
       @data.select { |k, _| k.is_a?(Symbol) }
     end
 
@@ -6168,8 +7735,18 @@ module Parse
       @raw_data
     end
 
+    # @return [Boolean] true in `:server` naming mode.
+    def server?
+      @field_names == :server
+    end
+
     # Method-style access to fields
     def method_missing(method_name, *args, &block)
+      if server?
+        key = server_key_for(method_name, strict: true)
+        return @data[key] if key
+        return super
+      end
       key = method_name.to_sym
       if @data.key?(key)
         @data[key]
@@ -6179,12 +7756,32 @@ module Parse
     end
 
     def respond_to_missing?(method_name, include_private = false)
+      return !server_key_for(method_name).nil? || super if server?
       @data.key?(method_name.to_sym) || super
     end
 
     def inspect
       "#<Parse::AggregationResult #{to_h.inspect}>"
     end
+
+    private
+
+    # Resolve a requested name to a stored key in `:server` mode: an exact
+    # match first, else the single key whose snake_case form equals it. Two
+    # or more snake_case matches are ambiguous (e.g. `totalPlays` and
+    # `total_plays` both stored): `strict:` raises naming them, otherwise nil.
+    def server_key_for(name, strict: false)
+      str = name.to_s
+      return str if @data.key?(str)
+      matches = @data.keys.select { |k| Parse::Query.to_snake_case(k) == str }
+      return matches.first if matches.length == 1
+      if matches.length > 1 && strict
+        raise ArgumentError,
+              "Parse::AggregationResult: #{str.inspect} matches several fields " \
+              "(#{matches.inspect}); read one with result[#{matches.first.inspect}]."
+      end
+      nil
+    end
   end
 
   # Helper class for executing arbitrary MongoDB aggregation pipelines.
@@ -6303,7 +7900,13 @@ module Parse
     #
     # @yield a block to iterate for each object in the result
     # @return [Array<Parse::Object, AggregationResult>] array of results
-    def results(&block)
+    #
+    # @param field_names [Symbol, nil] naming mode for AggregationResult rows:
+    #   `:default` (snake_case symbol keys from `#to_h`) or `:server` (keys
+    #   exactly as the aggregation returned them). Parse::Object rows are
+    #   unaffected; use `#as_json` for their server-named form.
+    def results(field_names: nil, &block)
+      @result_field_names = AggregationResult.normalize_field_names!(field_names)
       response = execute!
 
       if @mongo_direct && defined?(Parse::MongoDB) && Parse::MongoDB.enabled?
@@ -6333,7 +7936,7 @@ module Parse
       if looks_like_parse_document?(item)
         @query.send(:decode, [item]).first
       else
-        AggregationResult.new(item)
+        AggregationResult.new(item, field_names: @result_field_names)
       end
     end
 
@@ -6351,7 +7954,7 @@ module Parse
         @query.send(:redact_excluded_keys!, [parse_doc])
         @query.send(:decode, [parse_doc]).first
       else
-        AggregationResult.new(Parse::MongoDB.convert_aggregation_document(raw))
+        AggregationResult.new(Parse::MongoDB.convert_aggregation_document(raw), field_names: @result_field_names)
       end
     end
 
@@ -6667,7 +8270,9 @@ module Parse
       pipeline << sort if sort
       pipeline << { "$project" => { "_id" => 0, "objectId" => "$_id", "count" => 1 } }
 
-      @query.aggregate(pipeline, verbose: @query.instance_variable_get(:@verbose_aggregate)).raw || []
+      return [] if @query.instance_variable_get(:@limit) == 0
+      @query.aggregate(pipeline, verbose: @query.instance_variable_get(:@verbose_aggregate),
+                                 window_before_pipeline: true).raw || []
     end
 
     # Count the number of items in each group.
@@ -6799,6 +8404,9 @@ module Parse
       # what the caller meant.
       validate_sort_target_for_operation!(operation)
 
+      # `limit(0)` selects no rows, so there are no groups.
+      return {} if @query.instance_variable_get(:@limit) == 0
+
       # Format the group field name
       formatted_group_field = @query.send(:format_aggregation_field, @group_field)
 
@@ -6853,8 +8461,10 @@ module Parse
         },
       }
 
-      # Use the Aggregation class to execute
-      aggregation = @query.aggregate(pipeline, verbose: @query.instance_variable_get(:@verbose_aggregate))
+      # Use the Aggregation class to execute. The query's order / skip /
+      # limit pick the rows before `$group`.
+      aggregation = @query.aggregate(pipeline, verbose: @query.instance_variable_get(:@verbose_aggregate),
+                                               window_before_pipeline: true)
       raw_results = aggregation.raw
 
       # Convert array of results to hash
@@ -6922,6 +8532,10 @@ module Parse
         pipeline << { "$match" => mongo_constraints } if mongo_constraints.any?
       end
 
+      # The query's order / skip / limit pick the rows before `$group`.
+      window = @query.send(:query_window_stages)
+      pipeline.concat(@query.send(:translate_pipeline_for_direct_mongodb, window)) if window.any?
+
       # Add unwind stage if flatten_arrays is enabled
       if @flatten_arrays
         pipeline << { "$unwind" => "$#{mongo_group_field}" }
@@ -7987,3 +9601,93 @@ module Parse
     end
   end
 end # Parse
+
+module Parse
+  # Wraps the public compile and pipeline entry points of Parse::Query and
+  # the aggregation helpers so {Parse::Query.format_field} honors the model's
+  # explicit `field:` names (for example `account_id` or `authId_sub`) instead
+  # of camel-casing them. Without this, `where(account_id: ...)` compiled to
+  # `accountId` and silently matched nothing.
+  module QueryFieldAliasScope
+    QUERY_METHODS = %i[
+      add_constraint keys exclude_keys order includes pluck count_distinct
+      compile compile_where prepared pipeline count results distinct first first_direct
+      build_direct_mongodb_pipeline build_query_aggregate_pipeline build_aggregation_pipeline
+      aggregate group_by group_by_date explain sum average min max
+    ].freeze
+
+    # Aggregation helper methods that format field names while running.
+    HELPER_METHODS = %i[pipeline results count execute! sum average min max list raw].freeze
+
+    # The mongo-direct entry points are wrapped with their exact signatures
+    # (not `*args, **kwargs`), so `Method#parameters` still reports the
+    # `client:` keyword that client-binding checks rely on.
+    module DirectMethods
+      def results_direct(raw: false, max_time_ms: nil, session_token: nil, master: nil,
+                         acl_user: nil, acl_role: nil, client: nil, &block)
+        block = Parse::Query.block_outside_field_aliases(block, @table)
+        Parse::Query.with_field_aliases(@table) do
+          super(raw: raw, max_time_ms: max_time_ms, session_token: session_token, master: master,
+                acl_user: acl_user, acl_role: acl_role, client: client, &block)
+        end
+      end
+
+      def count_direct(session_token: nil, master: nil, acl_user: nil, acl_role: nil, client: nil)
+        Parse::Query.with_field_aliases(@table) do
+          super(session_token: session_token, master: master, acl_user: acl_user,
+                acl_role: acl_role, client: client)
+        end
+      end
+
+      def distinct_direct(field, return_pointers: false, order: nil, session_token: nil, master: nil,
+                          acl_user: nil, acl_role: nil, client: nil)
+        Parse::Query.with_field_aliases(@table) do
+          super(field, return_pointers: return_pointers, order: order, session_token: session_token,
+                master: master, acl_user: acl_user, acl_role: acl_role, client: client)
+        end
+      end
+
+      def distinct_direct_pointers(field, order: nil, session_token: nil, master: nil,
+                                   acl_user: nil, acl_role: nil, client: nil)
+        Parse::Query.with_field_aliases(@table) do
+          super(field, order: order, session_token: session_token, master: master,
+                acl_user: acl_user, acl_role: acl_role, client: client)
+        end
+      end
+    end
+
+    # @param klass [Class] the class whose methods are wrapped.
+    # @param methods [Array<Symbol>]
+    # @param table_of [Proc] `->(receiver) { parse_class_name }`.
+    def self.wrap(klass, methods, table_of)
+      private_methods = methods.select { |m| klass.private_method_defined?(m) }
+      protected_methods = methods.select { |m| klass.protected_method_defined?(m) }
+      mod = Module.new
+      methods.each do |m|
+        next unless klass.method_defined?(m) || klass.private_method_defined?(m)
+        # A call for the table already in scope goes straight to the
+        # original, so nested query building pays only the table lookup.
+        mod.send(:define_method, m) do |*args, **kwargs, &blk|
+          table = table_of.call(self)
+          frame = Fiber[Parse::Query::FIELD_ALIAS_SCOPE_KEY]
+          return super(*args, **kwargs, &blk) if frame && frame.open && table == frame.scope.table
+          blk = Parse::Query.block_outside_field_aliases(blk, table) if blk
+          Parse::Query.with_field_aliases(table) { super(*args, **kwargs, &blk) }
+        end
+      end
+      # Keep each wrapped method's original visibility.
+      mod.send(:private, *private_methods) unless private_methods.empty?
+      mod.send(:protected, *protected_methods) unless protected_methods.empty?
+      klass.prepend(mod)
+    end
+  end
+
+  QueryFieldAliasScope.wrap(Query, QueryFieldAliasScope::QUERY_METHODS,
+                            ->(query) { query.instance_variable_get(:@table) })
+  Query.prepend(QueryFieldAliasScope::DirectMethods)
+  [Aggregation, GroupBy, GroupByDate].each do |helper|
+    QueryFieldAliasScope.wrap(helper, QueryFieldAliasScope::HELPER_METHODS,
+                              ->(agg) { agg.instance_variable_get(:@query)&.table })
+  end
+end
+