parse-stack-next 5.5.4 → 5.5.5

data/lib/parse/model/object.rb

@@ -85,32 +85,32 @@ module Parse
   end
 
   # This is the core class for all app specific Parse table subclasses. This class
-  # in herits from Parse::Pointer since an Object is a Parse::Pointer with additional fields,
+  # inherits from Parse::Pointer since an Object is a Parse::Pointer with additional fields,
   # at a minimum, created_at, updated_at and ACLs. This class also handles all
   # the relational types of associations in a Parse application and handles the main CRUD operations.
   #
   # As the parent class to all custom subclasses, this class provides the default property schema:
   #
-  #   class Parse::Object
-  #      # All subclasses will inherit these properties by default.
+  #     class Parse::Object
+  #       # All subclasses will inherit these properties by default.
   #
-  #      # the objectId column of a record.
-  #      property :id, :string, field: :objectId
+  #       # the objectId column of a record.
+  #       property :id, :string, field: :objectId
   #
-  #      # The the last updated date for a record (Parse::Date)
-  #      property :updated_at, :date
+  #       # The last updated date for a record (Parse::Date)
+  #       property :updated_at, :date
   #
-  #      # The original creation date of a record (Parse::Date)
-  #      property :created_at, :date
+  #       # The original creation date of a record (Parse::Date)
+  #       property :created_at, :date
   #
-  #      # The Parse::ACL field
-  #      property :acl, :acl, field: :ACL
+  #       # The Parse::ACL field
+  #       property :acl, :acl, field: :ACL
   #
-  #   end
+  #     end
   #
   # Most Pointers and Object subclasses are treated the same. Therefore, defining a class Artist < Parse::Object
   # that only has `id` set, will be treated as a pointer. Therefore a Parse::Object can be in a "pointer" state
-  # based on the data that it contains. Becasue of this, it is possible to take a Artist instance
+  # based on the data that it contains. Because of this, it is possible to take an Artist instance
   # (in this example), that is in a pointer state, and fetch the rest of the data for that particular
   # record without having to create a new object. Doing so would now mark it as not being a pointer anymore.
   # This is important to the understanding on how relations and properties are handled.
@@ -125,7 +125,7 @@ module Parse
   #
   # Associations:
   #
-  # Parse supports a three main types of relational associations. One type of
+  # Parse supports three main types of relational associations. One type of
   # relation is the `One-to-One` association. This is implemented through a
   # specific column in Parse with a Pointer data type. This pointer column,
   # contains a local value that refers to a different record in a separate Parse
@@ -1329,25 +1329,25 @@ module Parse
     #
     #   @param hash [Hash] the hash representing the object.
     #     Untrusted by default: keys in
-    #     {Parse::Properties::PROTECTED_INITIALIZE_KEYS} (+sessionToken+,
-    #     +_rperm+, +_wperm+, +_hashed_password+, +authData+, +roles+)
-    #     are filtered out even when an +objectId+ is present. This
-    #     closes the mass-assignment hole where +klass.new(attacker_params)+
-    #     on a hash that happens to include +objectId+ would overwrite
+    #     {Parse::Properties::PROTECTED_INITIALIZE_KEYS} (`sessionToken`,
+    #     `_rperm`, `_wperm`, `_hashed_password`, `authData`, `roles`)
+    #     are filtered out even when an `objectId` is present. This
+    #     closes the mass-assignment hole where `klass.new(attacker_params)`
+    #     on a hash that happens to include `objectId` would overwrite
     #     session tokens, ACLs, and auth data. Use {Parse::Object.build}
     #     for trusted hydration from server JSON; it bypasses the filter.
     # @return [Parse::Object] a the corresponding Parse::Object or subclass.
     def initialize(opts = {})
-      # Trusted hydration is signalled by the +@_trusted_init+ instance
-      # variable rather than by a +trusted:+ keyword argument. Using a
-      # keyword would break subclasses that override +initialize(*args)+
-      # and call +super+ — Ruby 3 keyword-arg semantics would convert the
-      # kwarg into a positional Hash through the variadic +*args+ splat
-      # and the subsequent +super+ would arrive at this method with two
+      # Trusted hydration is signalled by the `@_trusted_init` instance
+      # variable rather than by a `trusted:` keyword argument. Using a
+      # keyword would break subclasses that override `initialize(*args)`
+      # and call `super` — Ruby 3 keyword-arg semantics would convert the
+      # kwarg into a positional Hash through the variadic `*args` splat
+      # and the subsequent `super` would arrive at this method with two
       # positional args. The internal hydration paths
       # ({Parse::Object.build}, {Parse::Pointer} autofetch,
-      # {Parse::User#session}) +allocate+ the object, set the ivar, then
-      # invoke +initialize+ so subclass overrides still fire and pick up
+      # {Parse::User#session}) `allocate` the object, set the ivar, then
+      # invoke `initialize` so subclass overrides still fire and pick up
       # the trust signal here.
       trusted = @_trusted_init == true
       @_trusted_init = nil
@@ -1369,7 +1369,7 @@ module Parse
         # sessionToken / _rperm / _wperm / _hashed_password / authData /
         # roles. The narrow list deliberately allows createdAt /
         # updatedAt / className / __type through so the legitimate
-        # +Klass.new("objectId" => id, "createdAt" => ts, …)+
+        # `Klass.new("objectId" => id, "createdAt" => ts, …)`
         # cache-rehydrate pattern keeps working.
         apply_attributes!(opts,
                           dirty_track: !dirty_track,
@@ -1772,13 +1772,13 @@ module Parse
     # @return [Parse::Object] an instance of the Parse subclass
     def self.build(json, table = nil, fetched_keys: nil, nested_fetched_keys: nil)
       # Precedence (most → least authoritative):
-      # 1. Caller-supplied +table+ — caller knows the expected class
+      # 1. Caller-supplied `table` — caller knows the expected class
       #    (e.g. webhook payload routed to a typed handler, has_many that
       #    knows its declared target class).
-      # 2. The subclass +parse_class+ when invoked on a Parse::Object
+      # 2. The subclass `parse_class` when invoked on a Parse::Object
       #    subclass directly (Song.build(json)).
       # 3. The className inside the JSON — only trusted when neither of
-      #    the above is available (e.g. base-class +Parse::Object.build+
+      #    the above is available (e.g. base-class `Parse::Object.build`
       #    on untyped JSON).
       # Warn on mismatch between an explicit caller class and the
       # payload-supplied className so type-confusion attacks surface in
@@ -1823,9 +1823,9 @@ module Parse
         # Trusted hydration: this path runs on server-side JSON (response
         # bodies, webhook payloads that have already been scrubbed,
         # autofetch results). Server responses legitimately include
-        # protected keys like +sessionToken+, +_rperm+ that must populate
-        # the in-memory object. Untrusted +klass.new(hash)+ callers
-        # default to filter those keys. The +@_trusted_init+ ivar is the
+        # protected keys like `sessionToken`, `_rperm` that must populate
+        # the in-memory object. Untrusted `klass.new(hash)` callers
+        # default to filter those keys. The `@_trusted_init` ivar is the
         # signal — see {#initialize} for why we don't use a kwarg.
         o.instance_variable_set(:@_trusted_init, true)
         o.send(:initialize, json)
@@ -2138,13 +2138,13 @@ class Array
   # Parse::Pointer or are a JSON Parse hash. If it is a hash, a Pare::Object will be built from it
   # if it constrains the proper fields. Non-convertible objects will be removed.
   #
-  # When +className+ is provided by the caller, it is treated as authoritative
-  # — incoming hash +className+ values are ignored. This blocks attacker-
+  # When `className` is provided by the caller, it is treated as authoritative
+  # — incoming hash `className` values are ignored. This blocks attacker-
   # controlled type confusion when this helper is invoked from typed
-  # associations (+has_many+, +belongs_to+) that already know the expected
+  # associations (`has_many`, `belongs_to`) that already know the expected
   # class.
   #
-  # When +className+ is +nil+ (caller is doing untyped array conversion),
+  # When `className` is `nil` (caller is doing untyped array conversion),
   # the helper falls back to the hash-supplied className for compatibility
   # with raw JSON deserialization callers.
   #

data/lib/parse/model/pointer.rb

@@ -86,7 +86,7 @@ module Parse
 
     # Assign the Parse objectId. Empty / nil values are permitted (Pointer
     # in unbound state); non-empty values must match {OBJECT_ID_FORMAT}.
-    # @raise [ArgumentError] when +value+ is a non-empty string that does
+    # @raise [ArgumentError] when `value` is a non-empty string that does
     #   not match the format.
     def id=(value)
       if value.nil?
@@ -255,9 +255,9 @@ module Parse
         obj = klass.build(result, parse_class, fetched_keys: top_level_keys, nested_fetched_keys: nested_keys.presence)
       else
         # Full fetch - create without partial fetch tracking. Trusted
-        # hydration: +result+ is the server response body, which
-        # legitimately carries +createdAt+/+updatedAt+/+sessionToken+
-        # and other PROTECTED_MASS_ASSIGNMENT_KEYS. The +@_trusted_init+
+        # hydration: `result` is the server response body, which
+        # legitimately carries `createdAt`/`updatedAt`/`sessionToken`
+        # and other PROTECTED_MASS_ASSIGNMENT_KEYS. The `@_trusted_init`
         # ivar tells {Parse::Object#initialize} to skip the protected-key
         # filter — see that method for why we don't use a kwarg.
         obj = klass.allocate

data/lib/parse/model/push.rb

@@ -74,14 +74,14 @@ module Parse
     # caller did not explicitly opt in via {Parse::Push.allow_broadcast}
     # or per-instance {#broadcast!}.
     #
-    # This is a fail-closed guard against the +to_audience+ /
-    # +to_audience_id+ class of footguns where a typo, deleted audience,
+    # This is a fail-closed guard against the `to_audience` /
+    # `to_audience_id` class of footguns where a typo, deleted audience,
     # or unset-param silently degrades a targeted push into a global one.
     class BroadcastNotAllowed < StandardError; end
 
     # Raised when {#to_audience} or {#to_audience_id} cannot resolve the
     # requested audience. Previously these methods warned and returned
-    # +self+, which let the subsequent +send!+ silently broadcast to every
+    # `self`, which let the subsequent `send!` silently broadcast to every
     # Installation. They now raise so typos and renames surface at the
     # call site instead.
     class AudienceNotFound < ArgumentError; end
@@ -89,9 +89,9 @@ module Parse
     # @!attribute [rw] allow_broadcast
     #   Whether {Parse::Push} permits an unconstrained push (no `where`,
     #   no `channels`) to broadcast to every Installation. Defaults to
-    #   +false+ — sending an unconstrained push raises {BroadcastNotAllowed}.
+    #   `false` — sending an unconstrained push raises {BroadcastNotAllowed}.
     #
-    #   Set to +true+ at boot for apps that legitimately broadcast (e.g.,
+    #   Set to `true` at boot for apps that legitimately broadcast (e.g.,
     #   `Parse::Push.allow_broadcast = true`). Or opt in per-instance with
     #   {#broadcast!}, which is auditable in code review.
     #   @return [Boolean]

data/lib/parse/mongodb.rb

@@ -28,15 +28,15 @@ module Parse
   # When writing aggregation pipelines for direct MongoDB queries, use MongoDB's native
   # field naming conventions:
   #
-  # - *Regular fields*: Use camelCase (e.g., +releaseDate+, +playCount+, +firstName+)
-  # - *Pointer fields*: Use +_p_+ prefix (e.g., +_p_author+, +_p_album+)
-  # - *Built-in dates*: Use +_created_at+ and +_updated_at+
-  # - *Field references*: Use +$fieldName+ syntax (e.g., +$releaseDate+, +$_p_author+)
+  # - *Regular fields*: Use camelCase (e.g., `releaseDate`, `playCount`, `firstName`)
+  # - *Pointer fields*: Use `_p_` prefix (e.g., `_p_author`, `_p_album`)
+  # - *Built-in dates*: Use `_created_at` and `_updated_at`
+  # - *Field references*: Use `$fieldName` syntax (e.g., `$releaseDate`, `$_p_author`)
   #
   # Results are automatically converted to Ruby-friendly format:
-  # - Field names converted to snake_case (+totalPlays+ → +total_plays+)
-  # - Custom aggregation results wrapped in +AggregationResult+ for method access
-  # - Parse documents returned as proper +Parse::Object+ instances
+  # - Field names converted to snake_case (`totalPlays` → `total_plays`)
+  # - Custom aggregation results wrapped in `AggregationResult` for method access
+  # - Parse documents returned as proper `Parse::Object` instances
   #
   # @example Aggregation pipeline with MongoDB field names
   #   pipeline = [
@@ -52,9 +52,9 @@ module Parse
   # == Date Comparisons
   #
   # MongoDB stores dates in UTC. When comparing dates in aggregation pipelines:
-  # - Use Ruby +Time+ objects for comparisons (automatically converted to BSON dates)
-  # - Ruby +Date+ objects (without time) are stored as midnight UTC
-  # - For accurate date-only comparisons, use +Time.utc(year, month, day)+
+  # - Use Ruby `Time` objects for comparisons (automatically converted to BSON dates)
+  # - Ruby `Date` objects (without time) are stored as midnight UTC
+  # - For accurate date-only comparisons, use `Time.utc(year, month, day)`
   #
   # @example Date comparison in aggregation
   #   # Compare with a specific UTC time
@@ -1460,7 +1460,7 @@ module Parse
       # @param max_time_ms [Integer, nil] optional server-side time limit in milliseconds.
       #   When provided, MongoDB will cancel the query if it exceeds this budget and
       #   the driver error is translated to {Parse::MongoDB::ExecutionTimeout}.
-      #   Pass +nil+ (the default) for no cap.
+      #   Pass `nil` (the default) for no cap.
       # @return [Array<Hash>] the raw results from MongoDB
       # @param rewrite_lookups [Boolean, nil] when true (default `nil` --
       #   reads `Parse.rewrite_lookups`), auto-rewrite LLM-style $lookup
@@ -1469,16 +1469,16 @@ module Parse
       # @param allow_internal_fields [Boolean] when true, skip the
       #   internal-fields denylist check (e.g. for SDK-generated ACL
       #   filters produced by {Parse::Query#readable_by_role} and friends
-      #   that legitimately reference +_rperm+/+_wperm+). The
-      #   DENIED_OPERATORS walk, forensic-operator-in-+$expr+ check, and
-      #   internal-field +$+-reference string check all still run.
-      #   Passed +true+ only from the SDK direct-execution sites that
+      #   that legitimately reference `_rperm`/`_wperm`). The
+      #   DENIED_OPERATORS walk, forensic-operator-in-`$expr` check, and
+      #   internal-field `$`-reference string check all still run.
+      #   Passed `true` only from the SDK direct-execution sites that
       #   build their pipeline entirely from {Parse::Query#compile_where}:
-      #   +Parse::Query#results_direct+, +#first_direct+ (via
-      #   +results_direct+), +#count_direct+, +#distinct_direct+,
-      #   +#atlas_search+ builder-block, and the two +#group_by_*+ direct
-      #   paths. The Agent MCP tool path and +Aggregation#execute_direct!+
-      #   keep the default +false+ so attacker-controlled or user-supplied
+      #   `Parse::Query#results_direct`, `#first_direct` (via
+      #   `results_direct`), `#count_direct`, `#distinct_direct`,
+      #   `#atlas_search` builder-block, and the two `#group_by_*` direct
+      #   paths. The Agent MCP tool path and `Aggregation#execute_direct!`
+      #   keep the default `false` so attacker-controlled or user-supplied
       #   aggregate stages cannot reach internal columns.
       # @param session_token [String, nil] when provided, the SDK
       #   resolves the token to the requesting user + role subscription
@@ -1582,7 +1582,7 @@ module Parse
         # are SDK-generated (not attacker-controlled), so no
         # re-validation is needed before they're handed to MongoDB.
         if (acl_stage = Parse::ACLScope.match_stage_for(resolution))
-          pipeline = [acl_stage] + pipeline
+          pipeline = prepend_or_fold_acl_match(pipeline, acl_stage)
         end
         pipeline = Parse::ACLScope.rewrite_pipeline(pipeline, resolution)
 
@@ -1673,6 +1673,64 @@ module Parse
         raise
       end
 
+      # Inject the scoped ACL `$match` at the front of a pipeline — UNLESS
+      # the first stage is `$geoNear`, which MongoDB requires to be
+      # pipeline stage 0. In that case fold the ACL predicate into
+      # `$geoNear.query` (a candidate-document pre-filter, semantically
+      # equivalent to a leading `$match`) so the stage-0 invariant holds
+      # and the scoped geo query still enforces `_rperm`.
+      #
+      # A scoped `geo_near` previously failed CLOSED here: the prepended
+      # `$match` pushed `$geoNear` off stage 0 and MongoDB rejected the
+      # whole pipeline. Post-fetch redaction (protectedFields / sub-doc /
+      # internal-field) runs regardless, so folding loses no enforcement.
+      #
+      # @param pipeline [Array<Hash>]
+      # @param acl_stage [Hash] `{ "$match" => <predicate> }` from
+      #   {Parse::ACLScope.match_stage_for}.
+      # @return [Array<Hash>] a new pipeline; caller stages are not mutated.
+      def prepend_or_fold_acl_match(pipeline, acl_stage)
+        geo_key = geo_near_stage_key(pipeline.first)
+        return [acl_stage] + pipeline unless geo_key
+
+        match_pred = acl_stage["$match"] || acl_stage[:$match]
+        geo = pipeline.first[geo_key].dup
+        # Match the stage's own key style: reuse an existing `query` key of
+        # either type, else follow the `$geoNear` key's type (string stage
+        # → "query", symbol stage → :query). The Mongo driver normalizes
+        # either way, but keeping one style avoids a duplicate query key.
+        q_key =
+          if geo.key?("query") then "query"
+          elsif geo.key?(:query) then :query
+          elsif geo_key.is_a?(String) then "query"
+          else :query
+          end
+        existing = geo[q_key]
+        geo[q_key] =
+          if existing.is_a?(Hash) && !existing.empty?
+            # `existing` is still the caller's own `$geoNear.query` hash
+            # (the outer `.dup` above is shallow). Embed a copy, not the
+            # original, so the folded pipeline and the caller's pipeline
+            # don't share a mutable hash — honoring the "caller stages are
+            # not mutated" contract in both directions.
+            { "$and" => [existing.dup, match_pred] }
+          else
+            match_pred
+          end
+        new_first = pipeline.first.dup
+        new_first[geo_key] = geo
+        [new_first] + pipeline[1..]
+      end
+
+      # @return [Symbol, String, nil] the `$geoNear` key (symbol or string
+      #   form) if `stage` is a `$geoNear` stage, else nil.
+      def geo_near_stage_key(stage)
+        return nil unless stage.is_a?(Hash)
+        return :$geoNear if stage.key?(:$geoNear)
+        return "$geoNear" if stage.key?("$geoNear")
+        nil
+      end
+
       # Execute a `$geoNear` aggregation against a collection, returning
       # documents sorted by proximity to `near` along with their computed
       # distance. `$geoNear` is the aggregation-pipeline analogue of
@@ -2048,10 +2106,10 @@ module Parse
       end
 
       # Convert a raw MongoDB aggregation row, coercing values (BSON ObjectIds,
-      # dates, nested documents) but preserving all field names including +_id+.
-      # Unlike {.convert_document_to_parse}, this does NOT rename +_id+ to
-      # +objectId+, because aggregation +$group+ stages reuse +_id+ as the
-      # group key (e.g. a pointer string like +"Workspace$abc"+) rather than as a
+      # dates, nested documents) but preserving all field names including `_id`.
+      # Unlike {.convert_document_to_parse}, this does NOT rename `_id` to
+      # `objectId`, because aggregation `$group` stages reuse `_id` as the
+      # group key (e.g. a pointer string like `"Workspace$abc"`) rather than as a
       # Parse object identifier.
       #
       # @param doc [Hash] a raw MongoDB aggregation result row
@@ -2379,7 +2437,7 @@ module Parse
       #   DENIED_OPERATORS walk still runs. Intended only for callers
       #   that built the pipeline via {Parse::Query}'s own constraint
       #   DSL (e.g. {Parse::Query#readable_by_role}); raw user-supplied
-      #   pipelines (Agent MCP tools) must keep the default +false+.
+      #   pipelines (Agent MCP tools) must keep the default `false`.
       #
       # Public for testability and for callers that want to validate
       # input before forwarding to {.find} / {.aggregate}.

data/lib/parse/pipeline_security.rb

@@ -282,10 +282,10 @@ module Parse
     # @param node [Hash, Array, Object] the structure to walk.
     # @param allow_internal_fields [Boolean] when true, skip the
     #   {INTERNAL_FIELDS_DENYLIST} check (e.g. for SDK-generated ACL
-    #   filters that legitimately reference +_rperm+/+_wperm+ via
+    #   filters that legitimately reference `_rperm`/`_wperm` via
     #   {Parse::Query#readable_by_role} and friends). The
     #   {DENIED_OPERATORS} walk and forensic-operator gating still
-    #   apply. Default +false+ for callers that forward raw,
+    #   apply. Default `false` for callers that forward raw,
     #   user-influenced pipelines (e.g. Agent MCP tools).
     # @raise [Error] if a denied operator is found at any depth.
     # @return [true]

data/lib/parse/query/constraints.rb

@@ -2550,21 +2550,21 @@ module Parse
 
     # @!visibility private
     # Shared helpers for the four ACL constraint subclasses
-    # (+:ACL.readable_by+, +:ACL.readable_by_role+, +:ACL.writable_by+,
-    # +:ACL.writable_by_role+). Collects a list of permission strings
+    # (`:ACL.readable_by`, `:ACL.readable_by_role`, `:ACL.writable_by`,
+    # `:ACL.writable_by_role`). Collects a list of permission strings
     # from a caller-supplied value of User/Role/Pointer/Array/String,
     # using {Parse::Role.all_for_user} (user inputs) and
     # {Parse::Role#all_parent_role_names} (role inputs) so the
     # traversal walks the inheritance direction Parse Server actually
-    # enforces. Prior implementations inlined +role.all_child_roles+,
+    # enforces. Prior implementations inlined `role.all_child_roles`,
     # which traverses the wrong direction and over-grants.
     module ACLPermissions
       module_function
 
-      # Expand a +:ACL.readable_by+ / +:ACL.writable_by+ value into a
-      # permission-string array. Uses explicit +is_a?+ calls (rather
-      # than +case/when+) so callers that pass duck-typed mocks with
-      # overridden +is_a?+ — common in the constraint test suite —
+      # Expand a `:ACL.readable_by` / `:ACL.writable_by` value into a
+      # permission-string array. Uses explicit `is_a?` calls (rather
+      # than `case/when`) so callers that pass duck-typed mocks with
+      # overridden `is_a?` — common in the constraint test suite —
       # continue to route correctly.
       # @param value [Parse::User, Parse::Role, Parse::Pointer, String, Array]
       # @return [Array<String>]
@@ -2612,9 +2612,9 @@ module Parse
         str == "public" ? "*" : str
       end
 
-      # Expand a +:ACL.readable_by_role+ / +:ACL.writable_by_role+ value
+      # Expand a `:ACL.readable_by_role` / `:ACL.writable_by_role` value
       # into a permission-string array. Differs from {.collect} by
-      # auto-prefixing bare strings with +"role:"+ and refusing
+      # auto-prefixing bare strings with `"role:"` and refusing
       # non-role arguments.
       # @param value [Parse::Role, Parse::Pointer, String, Array]
       # @return [Array<String>]
@@ -2686,18 +2686,18 @@ module Parse
 
       # Compile a final permission-string array into an aggregation
       # pipeline match-stage on the requested permission field. The
-      # +$exists: false+ branch is appended by {Parse::ACL.read_predicate}
-      # / {Parse::ACL.write_predicate} so a missing +_rperm+/+_wperm+
+      # `$exists: false` branch is appended by {Parse::ACL.read_predicate}
+      # / {Parse::ACL.write_predicate} so a missing `_rperm`/`_wperm`
       # (treated as public by Parse Server) still matches.
       # @param permissions [Array<String>]
-      # @param field [String] +"_rperm"+ or +"_wperm"+.
+      # @param field [String] `"_rperm"` or `"_wperm"`.
       # @return [Hash] aggregation-pipeline wrapper compatible with
       #   {Parse::Query}'s constraint-build contract.
       # @param strict [Boolean] when true, build an EXACT match: suppress
-      #   both the implicit public +"*"+ grant AND the missing-field
-      #   (+$exists: false+) branch, so only rows whose +_rperm+/+_wperm+
-      #   literally contains one of +permissions+ match. Used by the
-      #   +readable_by(..., strict: true)+ / +readable_by_exact+ surface.
+      #   both the implicit public `"*"` grant AND the missing-field
+      #   (`$exists: false`) branch, so only rows whose `_rperm`/`_wperm`
+      #   literally contains one of `permissions` match. Used by the
+      #   `readable_by(..., strict: true)` / `readable_by_exact` surface.
       def pipeline(permissions, field:, strict: false)
         deduped = permissions.compact.reject(&:empty?).uniq
         if deduped.empty?
@@ -2712,9 +2712,9 @@ module Parse
       end
 
       # @!visibility private
-      # Whether a +readable_by+ / +writable_by+ value expresses "no
-      # permissions" (master-key-only): +nil+, an empty Array, the String
-      # +"none"+, or the Symbol +:none+. These map to {.empty_pipeline}.
+      # Whether a `readable_by` / `writable_by` value expresses "no
+      # permissions" (master-key-only): `nil`, an empty Array, the String
+      # `"none"`, or the Symbol `:none`. These map to {.empty_pipeline}.
       def empty_intent?(value)
         return true if value.nil?
         return true if value == "none" || value == :none
@@ -2724,11 +2724,11 @@ module Parse
 
       # @!visibility private
       # The match for "no permissions": an explicit empty array. A missing
-      # +_rperm+/+_wperm+ is treated by Parse Server as PUBLIC — the
-      # opposite of master-only — so it must NOT match here. +$eq: []+
+      # `_rperm`/`_wperm` is treated by Parse Server as PUBLIC — the
+      # opposite of master-only — so it must NOT match here. `$eq: []`
       # already excludes a missing field (missing != []); the +$exists:
       # true+ guard documents that intent.
-      # @param field [String] +"_rperm"+ or +"_wperm"+.
+      # @param field [String] `"_rperm"` or `"_wperm"`.
       def empty_pipeline(field:)
         { "__aggregation_pipeline" => [
           { "$match" => { field => { "$exists" => true, "$eq" => [] } } },
@@ -2736,11 +2736,11 @@ module Parse
       end
 
       # @!visibility private
-      # Permission keys for a +not_readable_by+ / +not_writable_by+ value:
+      # Permission keys for a `not_readable_by` / `not_writable_by` value:
       # the expanded grant set (user→roles, role→parent roles) PLUS the
-      # public +"*"+ wildcard. A public row is readable/writable by everyone,
+      # public `"*"` wildcard. A public row is readable/writable by everyone,
       # so it must be EXCLUDED from a "not readable/writable by X" result —
-      # hence +"*"+ is added to the +$nin+ set. Returns +[]+ for an
+      # hence `"*"` is added to the `$nin` set. Returns `[]` for an
       # empty-intent value (no negation constraint is applied).
       # @return [Array<String>]
       def collect_for_negation(value)
@@ -2831,7 +2831,7 @@ module Parse
       register :readable_by
 
       # @return [Boolean] whether to compile an EXACT match (suppress the
-      #   implicit public +"*"+ grant and the missing-field branch).
+      #   implicit public `"*"` grant and the missing-field branch).
       #   Overridden by {ACLReadableByExactConstraint}.
       def strict?
         false
@@ -2855,10 +2855,10 @@ module Parse
     end
 
     # Strict variant of {ACLReadableByConstraint}: matches ONLY rows whose
-    # +_rperm+ literally contains one of the resolved permissions — no
-    # implicit public +"*"+ and no missing-+_rperm+ (public-by-absence) rows.
-    # Reached via +Query#readable_by(value, strict: true)+ or the
-    # +:ACL.readable_by_exact+ symbol operator. Use this for ownership /
+    # `_rperm` literally contains one of the resolved permissions — no
+    # implicit public `"*"` and no missing-`_rperm` (public-by-absence) rows.
+    # Reached via `Query#readable_by(value, strict: true)` or the
+    # `:ACL.readable_by_exact` symbol operator. Use this for ownership /
     # security audits ("which rows explicitly grant this principal") rather
     # than access simulation ("what can this principal read").
     class ACLReadableByExactConstraint < ACLReadableByConstraint
@@ -3185,23 +3185,23 @@ module Parse
       end
     end
 
-    # @deprecated Thin alias of {ACLReadableByConstraint}. The +:readable_by+
+    # @deprecated Thin alias of {ACLReadableByConstraint}. The `:readable_by`
     #   operator is registered by {ACLReadableByConstraint}; this constant is
     #   retained only so any code referencing it keeps working. The previous
     #   standalone implementation (no role expansion, no implicit public
-    #   +"*"+, divergent empty-ACL shape) has been removed — it never backed
-    #   the +:readable_by+ operator and silently disagreed with it.
+    #   `"*"`, divergent empty-ACL shape) has been removed — it never backed
+    #   the `:readable_by` operator and silently disagreed with it.
     class ReadableByConstraint < ACLReadableByConstraint
     end
 
     # @deprecated Alias of {ACLWritableByConstraint}. The British-spelled
-    #   +:writeable_by+ operator now resolves to the SAME public-inclusive,
-    #   role-expanding implementation as +:writable_by+ — previously it was a
+    #   `:writeable_by` operator now resolves to the SAME public-inclusive,
+    #   role-expanding implementation as `:writable_by` — previously it was a
     #   separate, strict, non-expanding constraint, so the one-letter spelling
     #   difference silently changed query semantics. For the old exact-match
     #   behavior (no implicit public, no role expansion, no missing-field),
-    #   use +readable_by(..., strict: true)+ / +writable_by(..., strict: true)+
-    #   or the +:writable_by_exact+ operator.
+    #   use `readable_by(..., strict: true)` / `writable_by(..., strict: true)`
+    #   or the `:writable_by_exact` operator.
     class WriteableByConstraint < ACLWritableByConstraint
       register :writeable_by
     end
@@ -3223,7 +3223,7 @@ module Parse
     #
     # @note "Not readable by X" excludes rows readable by X *directly*, *via
     #   any role X inherits*, AND *publicly* — so a User value expands its
-    #   roles and the public +"*"+ is always added to the exclusion set.
+    #   roles and the public `"*"` is always added to the exclusion set.
     # @note This constraint uses aggregation pipeline because Parse Server
     #   restricts direct queries on the internal _rperm field.
     class NotReadableByConstraint < Constraint