parse-stack-next 5.5.6 → 5.7.0

data/lib/parse/retrieval/retriever.rb

@@ -224,8 +224,7 @@ module Parse
       chunker ||= default_chunker
       text_wire = wire_name(klass, resolved_text_field)
 
-      raw_hits =
-        if hybrid
+      raw_hits = if hybrid
           fetch_hybrid_hits(klass, query, k, field, filter, merged_vector_filter,
                             tenant_scope, hybrid, scope_opts)
         else
@@ -253,8 +252,8 @@ module Parse
                           tenant_scope, hybrid, scope_opts)
       cfg = hybrid.is_a?(Hash) ? hybrid : {}
       lexical = (cfg[:lexical] || cfg["lexical"] || {}).dup
-      vector  = (cfg[:vector]  || cfg["vector"]  || {}).dup
-      fusion  = cfg[:fusion] || cfg["fusion"]
+      vector = (cfg[:vector] || cfg["vector"] || {}).dup
+      fusion = cfg[:fusion] || cfg["fusion"]
 
       lexical[:query] ||= query
       # Tenant scope must be AUTHORITATIVE in BOTH branches. The previous
@@ -278,8 +277,7 @@ module Parse
 
     # @!visibility private
     def resolve_class!(klass)
-      resolved =
-        case klass
+      resolved = case klass
         when nil
           nil
         when Class

data/lib/parse/schema/index_migrator.rb

@@ -110,7 +110,7 @@ module Parse
         managed, ours = partition_parse_managed(existing)
         to_create, in_sync, conflicts = diff_declarations(declared, ours)
         declared_names = declared.map { |d| d[:options][:name] }.compact.to_set
-        declared_sigs  = declared.map { |d| key_sig(d[:keys]) }.to_set
+        declared_sigs = declared.map { |d| key_sig(d[:keys]) }.to_set
         orphans = ours.reject do |idx|
           declared_sigs.include?(key_sig(idx["key"] || idx[:key])) ||
             declared_names.include?(idx["name"] || idx[:name])
@@ -122,21 +122,21 @@ module Parse
         after_with_drop = after_no_drop - orphans.size
 
         {
-          collection:               collection,
-          declared:                 declared,
-          existing:                 existing,
-          parse_managed:            managed.map { |i| i["name"] || i[:name] },
-          to_create:                to_create,
-          in_sync:                  in_sync,
-          conflicts:                conflicts,
-          orphans:                  orphans.map { |i| i["name"] || i[:name] }.compact,
-          capacity_used:            used,
-          capacity_after:           after_no_drop,
-          capacity_remaining:       max - after_no_drop,
-          capacity_ok:              after_no_drop <= max,
+          collection: collection,
+          declared: declared,
+          existing: existing,
+          parse_managed: managed.map { |i| i["name"] || i[:name] },
+          to_create: to_create,
+          in_sync: in_sync,
+          conflicts: conflicts,
+          orphans: orphans.map { |i| i["name"] || i[:name] }.compact,
+          capacity_used: used,
+          capacity_after: after_no_drop,
+          capacity_remaining: max - after_no_drop,
+          capacity_ok: after_no_drop <= max,
           capacity_after_with_drop: after_with_drop,
           capacity_remaining_with_drop: max - after_with_drop,
-          capacity_ok_with_drop:    after_with_drop <= max,
+          capacity_ok_with_drop: after_with_drop <= max,
         }
       end
 
@@ -181,7 +181,7 @@ module Parse
           p[:orphans].each do |name|
             confirm = "drop:#{collection}:#{name}"
             res = Parse::MongoDB.drop_index(collection, name, confirm: confirm,
-                                            allow_system_classes: collection.start_with?("_Join:"))
+                                                              allow_system_classes: collection.start_with?("_Join:"))
             dropped << name if res == :dropped
           end
         end
@@ -190,21 +190,21 @@ module Parse
           result = Parse::MongoDB.create_index(
             collection,
             decl[:keys],
-            name:                decl[:options][:name],
-            unique:              decl[:options][:unique] == true,
-            sparse:              decl[:options][:sparse] == true,
-            partial_filter:      decl[:options][:partial_filter],
-            expire_after:        decl[:options][:expire_after],
+            name: decl[:options][:name],
+            unique: decl[:options][:unique] == true,
+            sparse: decl[:options][:sparse] == true,
+            partial_filter: decl[:options][:partial_filter],
+            expire_after: decl[:options][:expire_after],
             allow_system_classes: collection.start_with?("_Join:"),
           )
           (result == :exists ? skipped : created) << decl
         end
 
         {
-          created:        created,
+          created: created,
           skipped_exists: skipped,
-          dropped:        dropped,
-          conflicts:      p[:conflicts],
+          dropped: dropped,
+          conflicts: p[:conflicts],
           capacity_blocked: false,
         }
       end
@@ -235,12 +235,12 @@ module Parse
 
       def diff_declarations(declared, existing_ours)
         to_create = []
-        in_sync   = []
+        in_sync = []
         conflicts = []
 
         declared.each do |decl|
           decl_sig = key_sig(decl[:keys])
-          named    = decl[:options][:name]
+          named = decl[:options][:name]
 
           # Prefer a name match when the declaration named one — that's
           # the operator's authoritative target. Otherwise match by key
@@ -280,7 +280,7 @@ module Parse
       def serialize_existing(idx)
         {
           name: idx["name"] || idx[:name],
-          key:  idx["key"]  || idx[:key],
+          key: idx["key"] || idx[:key],
           unique: idx["unique"] == true,
           sparse: idx["sparse"] == true,
           partial_filter: idx["partialFilterExpression"],

data/lib/parse/schema/search_index_migrator.rb

@@ -75,8 +75,8 @@ module Parse
         end
 
         to_create = []
-        in_sync   = []
-        drifted   = []
+        in_sync = []
+        drifted = []
 
         declared.each do |decl|
           target = existing_by_name[decl[:name]]
@@ -93,14 +93,14 @@ module Parse
         orphans = existing_by_name.keys.reject { |name| declared_names.include?(name) }
 
         {
-          collection:      coll,
-          declared:        declared,
-          existing:        existing,
+          collection: coll,
+          declared: declared,
+          existing: existing,
           atlas_available: available,
-          to_create:       to_create,
-          in_sync:         in_sync,
-          drifted:         drifted,
-          orphans:         orphans,
+          to_create: to_create,
+          in_sync: in_sync,
+          drifted: drifted,
+          orphans: orphans,
         }
       end
 
@@ -176,14 +176,14 @@ module Parse
         end
 
         {
-          created:         created,
-          skipped_exists:  skipped_exists,
-          in_sync:         p[:in_sync],
-          updated:         updated,
+          created: created,
+          skipped_exists: skipped_exists,
+          in_sync: p[:in_sync],
+          updated: updated,
           drifted_skipped: drifted_skipped,
-          dropped:         dropped,
+          dropped: dropped,
           orphans_skipped: orphans_skipped,
-          wait_results:    wait_results,
+          wait_results: wait_results,
         }
       end
 
@@ -321,10 +321,10 @@ module Parse
       # history, statusDetail) so operator-facing output stays readable.
       def serialize_existing(idx)
         {
-          name:               (idx["name"] || idx[:name]).to_s,
-          status:             (idx["status"] || idx[:status]).to_s,
-          queryable:          idx["queryable"] == true,
-          latest_definition:  idx["latestDefinition"] || idx[:latestDefinition],
+          name: (idx["name"] || idx[:name]).to_s,
+          status: (idx["status"] || idx[:status]).to_s,
+          queryable: idx["queryable"] == true,
+          latest_definition: idx["latestDefinition"] || idx[:latestDefinition],
         }
       end
 

data/lib/parse/stack/tasks.rb

@@ -110,7 +110,7 @@ module Parse
 
               batch_size = (ENV["BATCH_SIZE"] || "100").to_i
               batch_size = 100 if batch_size <= 0
-              dry_run    = ENV["DRY_RUN"].to_s.downcase == "true"
+              dry_run = ENV["DRY_RUN"].to_s.downcase == "true"
 
               if dry_run
                 puts "[parse:references:populate] DRY_RUN=true — no writes will be issued"
@@ -120,7 +120,7 @@ module Parse
                 fields = Array(klass._parse_reference_fields)
                 fields.each do |field_name|
                   populated_total = 0
-                  scanned_total   = 0
+                  scanned_total = 0
                   loops_without_progress = 0
                   loop do
                     # Query for records where the reference column is null/
@@ -207,7 +207,7 @@ module Parse
                   puts "    to_create:"
                   p[:to_create].each do |d|
                     flags = d[:options].dup
-                    name  = flags.delete(:name) || "(auto)"
+                    name = flags.delete(:name) || "(auto)"
                     puts "      + #{d[:keys].inspect}  name=#{name}  opts=#{flags.inspect}"
                   end
                 end
@@ -423,13 +423,13 @@ module Parse
                 end
 
                 update = ENV["UPDATE"].to_s.downcase == "true"
-                drop   = ENV["DROP"].to_s.downcase   == "true"
-                wait   = ENV["WAIT"].to_s.downcase   == "true"
+                drop = ENV["DROP"].to_s.downcase == "true"
+                wait = ENV["WAIT"].to_s.downcase == "true"
                 timeout = (ENV["WAIT_TIMEOUT"] || "600").to_i
                 modes = []
                 modes << "additive"
                 modes << "update-drifted" if update
-                modes << "drop-orphans"   if drop
+                modes << "drop-orphans" if drop
                 modes << "wait-for-ready (#{timeout}s)" if wait
                 puts "[parse:mongo:search_indexes:apply] mode: #{modes.join(" + ")}"
                 if drop

data/lib/parse/stack/version.rb

@@ -6,6 +6,6 @@ module Parse
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "5.5.6"
+    VERSION = "5.7.0"
   end
 end

data/lib/parse/stack.rb

@@ -5,6 +5,7 @@ require_relative "stack/version"
 require_relative "client"
 require_relative "query"
 require_relative "model/object"
+require_relative "access"
 require_relative "webhooks"
 require_relative "agent"
 require_relative "two_factor_auth"
@@ -303,7 +304,7 @@ module Parse
             "Parse.login: credentials rejected for #{username.inspect} (server returned no session)."
     end
     Fiber[SESSION_TOKEN_STATE_KEY] = user.session_token
-    Fiber[CURRENT_USER_STATE_KEY]  = user
+    Fiber[CURRENT_USER_STATE_KEY] = user
     user
   end
 
@@ -323,7 +324,7 @@ module Parse
   def self.logout(revoke: true)
     token = Fiber[SESSION_TOKEN_STATE_KEY]
     Fiber[SESSION_TOKEN_STATE_KEY] = nil
-    Fiber[CURRENT_USER_STATE_KEY]  = nil
+    Fiber[CURRENT_USER_STATE_KEY] = nil
     if revoke && token.is_a?(String) && !token.empty?
       begin
         Parse::Client.client.logout(token)
@@ -346,7 +347,7 @@ module Parse
     resolved = token.respond_to?(:session_token) ? token.session_token : token
     resolved = resolved.to_s if resolved
     Fiber[SESSION_TOKEN_STATE_KEY] = (resolved && !resolved.empty?) ? resolved : nil
-    Fiber[CURRENT_USER_STATE_KEY]  = nil
+    Fiber[CURRENT_USER_STATE_KEY] = nil
     Fiber[SESSION_TOKEN_STATE_KEY]
   end
 
@@ -721,17 +722,16 @@ module Parse
         next if duration_ms < threshold
         logger = respond_to?(:logger) ? Parse.logger : nil
         next unless logger
-        detail =
-          if name == "parse.mongodb.aggregate"
-            "stages=#{payload[:stage_count]} types=#{Array(payload[:stage_types]).join(',')}"
+        detail = if name == "parse.mongodb.aggregate"
+            "stages=#{payload[:stage_count]} types=#{Array(payload[:stage_types]).join(",")}"
           else
-            "filter=#{!!payload[:has_filter]} projection=#{Array(payload[:projection_keys]).join(',')}"
+            "filter=#{!!payload[:has_filter]} projection=#{Array(payload[:projection_keys]).join(",")}"
           end
         logger.warn(
           "[Parse::MongoDB] SLOW #{name} #{duration_ms}ms " \
-          "collection=#{payload[:collection]} scope=#{payload[:scope] || 'n/a'} " \
-          "#{detail} result_count=#{payload[:result_count] || 'n/a'} " \
-          "max_time_ms=#{payload[:max_time_ms] || 'n/a'}",
+          "collection=#{payload[:collection]} scope=#{payload[:scope] || "n/a"} " \
+          "#{detail} result_count=#{payload[:result_count] || "n/a"} " \
+          "max_time_ms=#{payload[:max_time_ms] || "n/a"}",
         )
       end
       ActiveSupport::Notifications.subscribe("parse.mongodb.aggregate", &handler)

data/lib/parse/vector_search/hybrid.rb

@@ -66,6 +66,22 @@ module Parse
       # uses a comparable internal oversample.
       DEFAULT_OVERSAMPLE_MULTIPLIER = 5
 
+      # Emitted once per {.search}, mirroring
+      # {Parse::VectorSearch::AS_NOTIFICATION_NAME} so hybrid attrition
+      # is observable through the same subscriber. Carries `method`
+      # (`:rrf_client` / `:rrf_native`), `branch_depth`,
+      # `candidate_window`, `post_filter_count`, `returned_count`, and
+      # `underfilled`.
+      #
+      # `branch_depth` is the rows each branch actually retained, and it
+      # legitimately DIFFERS between the two methods: the client path
+      # enforces ACL inside each branch, so it can retain the narrower
+      # fusion depth, while the native path enforces after
+      # `$rankFusion` and must therefore retain the full candidate
+      # window. Exact parity is not achievable while that ordering
+      # difference exists, so the number reported is the one that ran.
+      AS_NOTIFICATION_NAME = "parse.vector_search.hybrid"
+
       # Hard ceiling on the fused result count, matching
       # {Parse::VectorSearch::MAX_K}.
       MAX_K = Parse::VectorSearch::MAX_K
@@ -120,11 +136,11 @@ module Parse
           acc.values
              .sort_by { |e| [-e[:score], row_id(e[:doc]).to_s, e[:seq]] }
              .map do |e|
-               row = e[:doc].dup
-               row["_hybrid_score"] = e[:score]
-               row["_hybrid_ranks"] = e[:ranks]
-               row
-             end
+            row = e[:doc].dup
+            row["_hybrid_score"] = e[:score]
+            row["_hybrid_ranks"] = e[:ranks]
+            row
+          end
         end
 
         # Detect whether the cluster backing `collection` supports the
@@ -140,14 +156,21 @@ module Parse
         # cached per collection for {PROBE_CACHE_TTL}.
         #
         # @param collection [String] Parse class / Mongo collection name.
+        # @param authorizing_client [Parse::Client, nil] client whose
+        #   application binding must be checked before probing.
         # @return [Boolean]
-        def rank_fusion_supported?(collection)
+        def rank_fusion_supported?(collection, authorizing_client: nil)
+          # Check on every call, including cache hits. Otherwise a verdict
+          # cached by application A could bypass the unidentified/mismatched
+          # caller guard when application B asks about the same collection.
+          Parse::MongoDB.verify_client!(authorizing_client)
+
           key = collection.to_s
           now = monotonic
           cached = probe_cache_get(key, now)
           return cached unless cached.nil?
 
-          supported = run_probe(key)
+          supported = run_probe(key, authorizing_client: authorizing_client)
           probe_cache_put(key, supported, now)
           supported
         end
@@ -219,8 +242,15 @@ module Parse
                   "hybrid search: fusion[:method] must be :rrf, :rrf_client, or :rrf_native (got #{method.inspect})."
           end
           k_constant = fusion[:k_constant] || DEFAULT_K_CONSTANT
-          weights    = fusion[:weights]
-          oversample = [k_int * DEFAULT_OVERSAMPLE_MULTIPLIER, k_int].max
+          weights = fusion[:weights]
+          # Two distinct numbers, deliberately not one. `fusion_depth` is
+          # how many rows each branch RETAINS for RRF (bounded by
+          # VectorSearch::MAX_K, since it becomes a branch `k`);
+          # `candidate_window` is how many rows Atlas CONSIDERS before
+          # ACL enforcement (bounded by 10_000). Collapsing them lets
+          # the window be multiplied twice — once here and again inside
+          # VectorSearch.search — and lets a branch `k` exceed MAX_K.
+          fusion_depth, candidate_window = resolve_windows(k_int, vec[:candidate_limit])
 
           # NOTE (deviation from plan §8.3): the default fuses CLIENT-SIDE.
           # The native single-roundtrip `$rankFusion` path is OPT-IN
@@ -233,20 +263,103 @@ module Parse
           # two-aggregate client path unless a caller explicitly opts into
           # native AND the cluster supports it. Native still falls back to
           # the client path on any execution error.
-          if method == :rrf_native && rank_fusion_supported?(collection_name)
-            fused = run_native(collection_name, lex, vec, oversample,
-                               k_constant: k_constant, weights: weights, scope_opts: scope_opts)
-            return fused.first(k_int) if fused
+          if method == :rrf_native
+            native_resolution = Parse::ACLScope.resolve!(
+              scope_opts.dup, method_name: :"VectorSearch::Hybrid.search",
+            )
+            if rank_fusion_supported?(
+              collection_name,
+              authorizing_client: Parse::ACLScope.client_of(native_resolution),
+            )
+              # The native pipeline enforces ACL AFTER fusion, so its
+              # per-branch limit is the pre-ACL depth: the candidate
+              # window, not the fusion depth.
+              fused = run_native(collection_name, lex, vec, candidate_window,
+                                 k_constant: k_constant, weights: weights, scope_opts: scope_opts,
+                                 resolution: native_resolution)
+              if fused
+                trimmed = fused.first(k_int)
+                # Native retains the full candidate window per branch,
+                # NOT the client path's fusion depth: its ACL `$match`
+                # runs after `$rankFusion`, so the branch limit and the
+                # pre-ACL window are necessarily the same number. Report
+                # what actually executed rather than the client figure.
+                emit_hybrid_stats(collection_name: collection_name, k: k_int,
+                                  method: :rrf_native, branch_depth: candidate_window,
+                                  candidate_window: candidate_window,
+                                  post_filter_count: fused.length,
+                                  returned_count: trimmed.length)
+                return trimmed
+              end
+            end
           end
 
-          lexical_rows = run_lexical(collection_name, lex, oversample, scope_opts)
-          vector_rows  = run_vector(collection_name, vec, oversample, scope_opts)
-          rrf({ lexical: lexical_rows, vector: vector_rows },
-              k_constant: k_constant, weights: weights).first(k_int)
+          lexical_rows = run_lexical(collection_name, lex, fusion_depth, scope_opts)
+          vector_rows = run_vector(collection_name, vec, fusion_depth, candidate_window, scope_opts)
+          fused = rrf({ lexical: lexical_rows, vector: vector_rows },
+                      k_constant: k_constant, weights: weights)
+          trimmed = fused.first(k_int)
+          emit_hybrid_stats(collection_name: collection_name, k: k_int,
+                            method: :rrf_client, branch_depth: fusion_depth,
+                            candidate_window: candidate_window,
+                            post_filter_count: fused.length,
+                            returned_count: trimmed.length)
+          trimmed
         end
 
         private
 
+        # Resolve the two windows.
+        #
+        # * `candidate_window` — rows Atlas considers before ACL. Never
+        #   narrower than the plain search's window, so opting into
+        #   hybrid cannot make ACL underfill worse than a straight
+        #   vector search. Bounded by Atlas's 10_000 ceiling.
+        # * `fusion_depth` — rows each branch retains for RRF. This
+        #   becomes a branch `k`, so it is additionally bounded by
+        #   VectorSearch::MAX_K; without that bound a hybrid `k` above
+        #   100 produces a branch `k` the plain search refuses outright.
+        #
+        # An out-of-range explicit `candidate_limit` is REFUSED rather
+        # than clamped: silently shrinking a caller's stated window
+        # would hide the very underfill they were trying to avoid.
+        #
+        # @return [Array(Integer, Integer)] `[fusion_depth, candidate_window]`
+        def resolve_windows(k_int, candidate_limit)
+          window = if candidate_limit
+              limit = Integer(candidate_limit)
+              if limit < k_int
+                raise ArgumentError,
+                      "hybrid search: vector[:candidate_limit] (#{limit}) must be >= k (#{k_int})."
+              end
+              if limit > Parse::VectorSearch::MAX_CANDIDATE_LIMIT
+                raise ArgumentError,
+                      "hybrid search: vector[:candidate_limit] (#{limit}) exceeds the Atlas " \
+                      "ceiling (#{Parse::VectorSearch::MAX_CANDIDATE_LIMIT})."
+              end
+              limit
+            else
+              multiplier = [DEFAULT_OVERSAMPLE_MULTIPLIER,
+                            Parse::VectorSearch::DEFAULT_CANDIDATE_MULTIPLIER].max
+              [[k_int * multiplier, k_int].max,
+               Parse::VectorSearch::MAX_CANDIDATE_LIMIT].min
+            end
+
+          depth = [[window, Parse::VectorSearch::MAX_K].min, k_int].max
+          [depth, window]
+        end
+
+        # Mirrors the plain search's attrition telemetry. `post_filter_count`
+        # is the fused row count after each branch has enforced ACL/CLP;
+        # `underfilled` means the caller received fewer than `k`.
+        def emit_hybrid_stats(**payload)
+          return unless defined?(ActiveSupport::Notifications)
+
+          payload[:underfilled] = payload[:returned_count] < payload[:k]
+          ActiveSupport::Notifications.instrument(AS_NOTIFICATION_NAME, payload)
+          nil
+        end
+
         # -- client-side branch execution --------------------------------
 
         def run_lexical(collection_name, lex, oversample, scope_opts)
@@ -263,12 +376,16 @@ module Parse
           )
         end
 
-        def run_vector(collection_name, vec, oversample, scope_opts)
+        def run_vector(collection_name, vec, fusion_depth, candidate_window, scope_opts)
           Parse::VectorSearch.search(
             collection_name,
             field: vec[:field],
             query_vector: vec[:query_vector],
-            k: oversample,
+            # `k` is what this branch keeps; `candidate_limit` is the
+            # pre-ACL window. Passing the window as `k` and letting the
+            # plain search derive its own would multiply it twice.
+            k: fusion_depth,
+            candidate_limit: candidate_window,
             num_candidates: vec[:num_candidates],
             filter: vec[:filter],
             vector_filter: vec[:vector_filter],
@@ -312,11 +429,17 @@ module Parse
           fusion = symbolize(fusion || {})
           lex = symbolize(lexical || {})
           vec = symbolize(vector || {})
-          oversample = [Integer(k) * DEFAULT_OVERSAMPLE_MULTIPLIER, Integer(k)].max
+          # Same resolution the live path uses, so the shape this
+          # returns is the shape that actually executes.
+          _depth, candidate_window = resolve_windows(Integer(k), vec[:candidate_limit])
           resolution = Parse::ACLScope.resolve!(scope_opts.dup, method_name: :"VectorSearch::Hybrid.search")
-          native_pipeline_for(lex, vec, oversample, resolution,
+          # `limit:` must match {#run_native}'s — the final `$limit` runs
+          # AFTER the ACL `$match`, so trimming to `k` there would
+          # reintroduce the underfill the window exists to prevent. The
+          # trim to `k` happens client-side once enforcement is done.
+          native_pipeline_for(lex, vec, candidate_window, resolution,
                               k_constant: fusion[:k_constant] || DEFAULT_K_CONSTANT,
-                              weights: fusion[:weights], limit: Integer(k))
+                              weights: fusion[:weights], limit: candidate_window)
         end
 
         def native_pipeline_for(lex, vec, oversample, resolution, k_constant:, weights:, limit:)
@@ -333,8 +456,8 @@ module Parse
           pipeline
         end
 
-        def run_native(collection_name, lex, vec, oversample, k_constant:, weights:, scope_opts:)
-          resolution = Parse::ACLScope.resolve!(scope_opts.dup, method_name: :"VectorSearch::Hybrid.search")
+        def run_native(collection_name, lex, vec, oversample, k_constant:, weights:, scope_opts:, resolution: nil)
+          resolution ||= Parse::ACLScope.resolve!(scope_opts.dup, method_name: :"VectorSearch::Hybrid.search")
           assert_clp_find!(collection_name, resolution)
           pointer_fields = resolve_pointer_fields!(collection_name, resolution)
           protected_fields = Parse::CLPScope.protected_fields_for(
@@ -347,7 +470,8 @@ module Parse
 
           pipeline = native_pipeline_for(lex, vec, oversample, resolution,
                                          k_constant: k_constant, weights: weights, limit: oversample)
-          rows = run_pipeline!(collection_name, pipeline)
+          rows = run_pipeline!(collection_name, pipeline,
+                               authorizing_client: Parse::ACLScope.client_of(resolution))
 
           unless resolution.master?
             # Defense-in-depth top-level row gate. The in-pipeline ACL
@@ -407,11 +531,11 @@ module Parse
           num_candidates = (vec[:num_candidates] || oversample * Parse::VectorSearch::DEFAULT_NUM_CANDIDATES_MULTIPLIER).to_i
           num_candidates = [[num_candidates, oversample].max, 10_000].min
           stage = {
-            "index"         => vec[:index].to_s,
-            "path"          => vec[:field].to_s,
-            "queryVector"   => vec[:query_vector],
+            "index" => vec[:index].to_s,
+            "path" => vec[:field].to_s,
+            "queryVector" => vec[:query_vector],
             "numCandidates" => num_candidates,
-            "limit"         => oversample,
+            "limit" => oversample,
           }
           stage["filter"] = vec[:vector_filter] if vec[:vector_filter] && !vec[:vector_filter].empty?
           inner = [{ "$vectorSearch" => stage }]
@@ -435,10 +559,18 @@ module Parse
 
         # -- the $rankFusion support probe -------------------------------
 
-        def run_probe(collection_name)
-          coll = Parse::MongoDB.collection(collection_name)
+        # Capability probe only: runs `$rankFusion` with an empty input and a
+        # `$limit 0`, so it reads no rows. It still carries the authorizing
+        # client because the process-global MongoDB connection must enforce
+        # its application binding even for a zero-row probe.
+        def run_probe(collection_name, authorizing_client: nil)
+          coll = Parse::MongoDB.collection(collection_name, authorizing_client: authorizing_client)
           coll.aggregate([{ "$rankFusion" => { "input" => {} } }, { "$limit" => 0 }]).to_a
           true
+        rescue Parse::MongoDB::ClientMismatch
+          # A binding violation is not evidence that the stage exists. It is a
+          # security boundary and must reach the caller without being cached.
+          raise
         rescue StandardError => e
           # "Unknown aggregation stage $rankFusion" (or an unrecognized-
           # operator variant) means the cluster predates native support.
@@ -534,8 +666,9 @@ module Parse
           end
         end
 
-        def run_pipeline!(collection_name, pipeline)
-          Parse::MongoDB.collection(collection_name).aggregate(pipeline).to_a
+        def run_pipeline!(collection_name, pipeline, authorizing_client: nil)
+          Parse::MongoDB.collection(collection_name, authorizing_client: authorizing_client)
+                        .aggregate(pipeline).to_a
         end
 
         def assert_clp_find!(collection_name, resolution)