parse-stack-next 5.5.4 → 5.5.5

data/lib/parse/agent.rb

@@ -739,7 +739,7 @@ module Parse
 
     # Built-in mutation tools that route through session-token REST and
     # are therefore enforceable by Parse Server's native ACL/CLP. Gated
-    # additionally by the per-agent +allow_mutations:+ kwarg in client
+    # additionally by the per-agent `allow_mutations:` kwarg in client
     # mode (default false) and by the existing process-level env vars
     # (PARSE_AGENT_ALLOW_WRITE_TOOLS + PARSE_AGENT_ALLOW_RAW_CRUD).
     CLIENT_SAFE_MUTATION_TOOLS = %i[
@@ -806,7 +806,7 @@ module Parse
       #   configure this on load.
       attr_accessor :allowed_llm_endpoints
 
-      # Validate +endpoint+ against {allowed_llm_endpoints}. No-op
+      # Validate `endpoint` against {allowed_llm_endpoints}. No-op
       # when the allowlist is unset. Raises `ArgumentError` on miss so
       # the caller's `ask` / `ask_streaming` invocation fails before
       # any HTTP request is sent.
@@ -887,29 +887,29 @@ module Parse
     attr_reader :session_token
 
     # @return [Parse::User, Parse::Pointer, nil] the User identity the
-    #   agent was constructed with via +acl_user:+. The agent's
+    #   agent was constructed with via `acl_user:`. The agent's
     #   {#acl_scope} resolves this user's permission_strings
     #   (objectId + roles, expanded) at construction. nil for
     #   session_token / acl_role / master-key construction.
     attr_reader :acl_user_scope
 
     # @return [Parse::Role, String, Symbol, nil] the Role identity the
-    #   agent was constructed with via +acl_role:+. Used for
+    #   agent was constructed with via `acl_role:`. Used for
     #   service-account-style scoping ("see as if a user with this
     #   role were asking") without a specific user. nil for
     #   session_token / acl_user / master-key construction.
     attr_reader :acl_role_scope
 
     # @return [Parse::ACLScope::Resolution, nil] the resolved ACL scope
-    #   for this agent. Frozen at construction. +nil+ means master-key
+    #   for this agent. Frozen at construction. `nil` means master-key
     #   posture — the agent runs every tool call with the application
     #   master key, bypassing per-row ACL/CLP enforcement. Non-nil
-    #   carries a +permission_strings+ allow-set that built-in tools
+    #   carries a `permission_strings` allow-set that built-in tools
     #   forward to mongo-direct / Atlas Search via {#acl_scope_kwargs}.
     attr_reader :acl_scope
 
     # @return [Boolean] whether this agent may run Atlas Search tools
-    #   in master-key-equivalent mode when no +session_token+ is set.
+    #   in master-key-equivalent mode when no `session_token` is set.
     #   See {#master_atlas?} for the gate semantics applied by the
     #   Atlas Search tool handlers in {Parse::Agent::Tools}.
     attr_reader :master_atlas
@@ -921,7 +921,7 @@ module Parse
     #   Parse::Client has no master_key). In client mode the dispatchable
     #   tool set is restricted to {CLIENT_SAFE_READ_TOOLS},
     #   {CLIENT_SAFE_MUTATION_TOOLS} (gated on {#allow_mutations?}), and
-    #   any registered tool declared +client_safe: true+.
+    #   any registered tool declared `client_safe: true`.
     def client_mode?
       @client_mode == true
     end
@@ -930,7 +930,7 @@ module Parse
     #   tools (create_object/update_object/delete_object). Layered with
     #   the process-level PARSE_AGENT_ALLOW_WRITE_TOOLS +
     #   PARSE_AGENT_ALLOW_RAW_CRUD env vars (all three must be true).
-    #   Default: +false+ in client mode, +true+ in master-key mode.
+    #   Default: `false` in client mode, `true` in master-key mode.
     def allow_mutations?
       @allow_mutations == true
     end
@@ -1050,10 +1050,10 @@ module Parse
       tok.cancelled?
     end
 
-    # @return [Boolean] +true+ when this agent has been explicitly
-    #   constructed with +master_atlas: true+. Used by the Atlas
+    # @return [Boolean] `true` when this agent has been explicitly
+    #   constructed with `master_atlas: true`. Used by the Atlas
     #   Search tool handlers in {Parse::Agent::Tools} to gate calls
-    #   that would otherwise refuse because no +session_token+ is
+    #   that would otherwise refuse because no `session_token` is
     #   available — see {Parse::AtlasSearch} for the reasoning behind
     #   the dedicated opt-in (Atlas Search bypasses Parse Server
     #   entirely, so the agent's normal master-key posture is not a
@@ -1098,7 +1098,7 @@ module Parse
     # The agent's resolved identity claim set — the
     # `["*", userObjectId, "role:Foo", ...]` array that gets matched
     # against a document's `_rperm` (for read) or `_wperm` (for
-    # write). Returns +nil+ for master-key posture (unrestricted reach
+    # write). Returns `nil` for master-key posture (unrestricted reach
     # — no filtering applied).
     #
     # The set is identity-based and identical for read and write
@@ -1113,7 +1113,7 @@ module Parse
     # A ready-to-prepend `$match` stage filtering an aggregation
     # pipeline to documents the agent's scope is allowed to READ.
     # Mirrors what the built-in read tools inject automatically via
-    # {Parse::ACLScope.match_stage_for}. Returns +nil+ for master-key
+    # {Parse::ACLScope.match_stage_for}. Returns `nil` for master-key
     # posture.
     #
     # @return [Hash, nil]
@@ -1129,7 +1129,7 @@ module Parse
     # perform writes (e.g., a custom `agent_method` that batch-updates
     # rows under the agent's scope) prepend this stage themselves so
     # the update only sees rows whose `_wperm` includes the agent's
-    # identity. Returns +nil+ for master-key posture.
+    # identity. Returns `nil` for master-key posture.
     #
     # @return [Hash, nil]
     def acl_write_match_stage
@@ -1138,11 +1138,11 @@ module Parse
       { "$match" => Parse::ACL.write_predicate(perms) }
     end
 
-    # +true+ when the agent carries any non-master-key scope
+    # `true` when the agent carries any non-master-key scope
     # (session_token, acl_user, or acl_role). Use this when deciding
     # whether a Parse Server endpoint that DOES NOT enforce ACL
     # (notably the REST `aggregate` endpoint) is safe to route through:
-    # any +true+ here means the REST path would silently bypass the
+    # any `true` here means the REST path would silently bypass the
     # agent's declared scope, so the tool must use the mongo-direct
     # path (which runs Parse::ACLScope's `_rperm` injection).
     #
@@ -1151,11 +1151,11 @@ module Parse
       !@acl_scope.nil?
     end
 
-    # +true+ when the agent's ACL scope cannot be honored by Parse
+    # `true` when the agent's ACL scope cannot be honored by Parse
     # Server's REST surface at all (no "act as role" affordance) and
     # the SDK must auto-route every built-in tool through mongo-direct
     # (Parse::MongoDB.aggregate / Parse::Query#results_direct). Fires
-    # ONLY for +acl_user:+ and +acl_role:+ scopes; session_token
+    # ONLY for `acl_user:` and `acl_role:` scopes; session_token
     # agents can keep the REST find_objects path because Parse Server
     # validates the token natively for find / get endpoints.
     #
@@ -1170,7 +1170,7 @@ module Parse
       !(@acl_user_scope.nil? && @acl_role_scope.nil?)
     end
 
-    # +true+ when an AGGREGATE operation for this agent MUST run through
+    # `true` when an AGGREGATE operation for this agent MUST run through
     # the SDK's mongo-direct path (Parse::MongoDB.aggregate) instead of
     # Parse Server's REST aggregate endpoint. The REST aggregate endpoint
     # enforces NEITHER ACL, CLP, nor protectedFields and requires the
@@ -1183,7 +1183,7 @@ module Parse
     # REST find/get DOES enforce a session token — but REST aggregate does
     # not). Fires for acl_user / acl_role scopes AND for any session-token
     # identity, including a runtime-impersonated agent whose @acl_scope has
-    # been cleared. Master-key agents return +false+.
+    # been cleared. Master-key agents return `false`.
     #
     # @return [Boolean]
     def requires_mongo_direct?
@@ -1766,7 +1766,7 @@ module Parse
       #                           false default would silently disable
       #                           writes for every existing master-key
       #                           agent).
-      # When +parent:+ is supplied, the child cannot widen the parent's
+      # When `parent:` is supplied, the child cannot widen the parent's
       # gate: if parent.allow_mutations? is false, child must also be
       # false. Default-on-nil inherits the parent's value verbatim so
       # the safe path (omit kwarg) is trivially correct.
@@ -2543,6 +2543,18 @@ module Parse
           details = e.respond_to?(:to_details) ? e.to_details : {}
           response = error_response(e.message, error_code: :access_denied, details: details.any? ? details : nil)
 
+          # Recognized-but-unimplemented tool (the built-in write/admin
+          # CRUD tools ship without a handler). Surface the actionable
+          # message rather than collapsing to the opaque internal-error
+          # path, and tag a distinct :not_implemented code so callers can
+          # branch on "tool doesn't exist here" vs a real failure.
+        rescue Parse::Agent::NotImplemented => e
+          trigger_callbacks(:on_error, e, { tool: tool_name, args: kwargs })
+          payload[:success]     = false
+          payload[:error_class] = e.class.name
+          payload[:error_code]  = :not_implemented
+          response = error_response(e.message, error_code: :not_implemented)
+
           # Validation errors (e.g. from registered tool handlers or get_objects)
         rescue Parse::Agent::ValidationError => e
           trigger_callbacks(:on_error, e, { tool: tool_name, args: kwargs })
@@ -3012,7 +3024,7 @@ module Parse
     # {#import_conversation}.
     IMPORT_MAX_CONTENT_LEN = 32 * 1024
     # @!visibility private
-    # Roles permitted on imported conversation entries. +system+ and +tool+
+    # Roles permitted on imported conversation entries. `system` and `tool`
     # are explicitly excluded — without this guard, an attacker who
     # controls a saved transcript can plant fabricated tool results
     # (which the next LLM turn treats as authentic prior retrievals) or
@@ -3024,10 +3036,10 @@ module Parse
     # conversation history and token usage. Permissions are NEVER
     # restored from the export — they belong to the Agent constructor.
     #
-    # Only +role: "user"+ and +role: "assistant"+ entries with
-    # String/nil +content+ are accepted. Disallowed roles, oversized
+    # Only `role: "user"` and `role: "assistant"` entries with
+    # String/nil `content` are accepted. Disallowed roles, oversized
     # content, or message counts above {IMPORT_MAX_MESSAGES} raise
-    # +ArgumentError+; a malformed JSON payload returns +false+ with a
+    # `ArgumentError`; a malformed JSON payload returns `false` with a
     # warning.
     #
     # @param json_string [String] JSON string from {#export_conversation}.
@@ -3761,11 +3773,11 @@ module Parse
 
     # Get the current authentication context.
     #
-    # @return [Hash] +:type+ is one of +:session_token+, +:acl_user+,
-    #   +:acl_role+, or +:master_key+. +:using_master_key+ is +true+
-    #   ONLY for +:master_key+; scoped agents (session_token / acl_user /
+    # @return [Hash] `:type` is one of `:session_token`, `:acl_user`,
+    #   `:acl_role`, or `:master_key`. `:using_master_key` is `true`
+    #   ONLY for `:master_key`; scoped agents (session_token / acl_user /
     #   acl_role) run with explicit ACL enforcement and never set the
-    #   master-key flag. The +:identity+ slot carries a posture-specific
+    #   master-key flag. The `:identity` slot carries a posture-specific
     #   identifier (user_id for session/acl_user, role name for
     #   acl_role, nil for master_key) so the AUDIT log can attribute
     #   tool calls accurately.

data/lib/parse/api/aggregate.rb

@@ -25,7 +25,7 @@ module Parse
       module ClassMethods
         # Get the aggregate API path for this class.
         #
-        # +className+ is validated to prevent path-smuggling — aggregate
+        # `className` is validated to prevent path-smuggling — aggregate
         # endpoints are master-key-only on Parse Server, so any traversal
         # here pivots a master-key request to a different endpoint.
         #
@@ -66,9 +66,9 @@ module Parse
       # @param pipeline [Array] the MongoDB aggregation pipeline stages.
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @param headers [Hash] additional HTTP headers to send with the request.
-      # @param raw_values [Boolean] when true, adds +rawValues: true+ to the request
+      # @param raw_values [Boolean] when true, adds `rawValues: true` to the request
       #   so Parse Server returns un-decoded field values (PS 9.9.0+, #10438).
-      # @param raw_field_names [Boolean] when true, adds +rawFieldNames: true+ to the
+      # @param raw_field_names [Boolean] when true, adds `rawFieldNames: true` to the
       #   request so Parse Server returns original (un-decoded) field names (PS 9.9.0+).
       # @return [Parse::Response]
       # @see Parse::Query

data/lib/parse/api/cloud_functions.rb

@@ -9,31 +9,40 @@ module Parse
       # Call a cloud function.
       # @param name [String] the name of the cloud function.
       # @param body [Hash] the parameters to forward to the function.
-      # @param opts [Hash] additional options for the request.
+      # @param opts [Hash] additional options for the request. Accepts the
+      #   explicit `opts:` hash for back-compat, but request options may
+      #   also be passed as plain keyword arguments (e.g.
+      #   `call_function("f", {}, session_token: t)`) to match the rest of
+      #   the API surface — those are merged into `opts` (explicit `opts:`
+      #   keys win on conflict).
       # @option opts [String] :session_token The session token for authenticated requests.
       # @option opts [String] :master_key Whether to use the master key for this request.
       # @param context [Hash, nil] an optional caller context forwarded as the
-      #   +X-Parse-Cloud-Context+ header. Parse Server maps it to
-      #   +req.info.context+ in the cloud function handler.
-      #   Omit or pass +nil+ to leave behavior unchanged.
+      #   `X-Parse-Cloud-Context` header. Parse Server maps it to
+      #   `req.info.context` in the cloud function handler.
+      #   Omit or pass `nil` to leave behavior unchanged.
       # @return [Parse::Response]
-      def call_function(name, body = {}, opts: {}, context: nil)
+      def call_function(name, body = {}, opts: {}, context: nil, **kwopts)
         safe = Parse::API::PathSegment.identifier!(name, kind: "function name")
         headers = {}
         headers[Parse::Protocol::CLOUD_CONTEXT] = context.to_json unless context.nil?
-        request :post, "functions/#{safe}", body: body, headers: headers, opts: opts
+        merged = kwopts.empty? ? opts : kwopts.merge(opts)
+        request :post, "functions/#{safe}", body: body, headers: headers, opts: merged
       end
 
       # Trigger a job.
       # @param name [String] the name of the job to trigger.
       # @param body [Hash] the parameters to forward to the job.
-      # @param opts [Hash] additional options for the request.
+      # @param opts [Hash] additional options for the request. Like
+      #   {#call_function}, request options may be passed either as the
+      #   explicit `opts:` hash or as plain keyword arguments.
       # @option opts [String] :session_token The session token for authenticated requests.
       # @option opts [String] :master_key Whether to use the master key for this request.
       # @return [Parse::Response]
-      def trigger_job(name, body = {}, opts: {})
+      def trigger_job(name, body = {}, opts: {}, **kwopts)
         safe = Parse::API::PathSegment.identifier!(name, kind: "job name")
-        request :post, "jobs/#{safe}", body: body, opts: opts
+        merged = kwopts.empty? ? opts : kwopts.merge(opts)
+        request :post, "jobs/#{safe}", body: body, opts: merged
       end
 
       # Call a cloud function with a specific session token.
@@ -42,7 +51,7 @@ module Parse
       # @param body [Hash] the parameters to forward to the function.
       # @param session_token [String] the session token for authenticated requests.
       # @param context [Hash, nil] an optional caller context forwarded as the
-      #   +X-Parse-Cloud-Context+ header.
+      #   `X-Parse-Cloud-Context` header.
       # @return [Parse::Response]
       def call_function_with_session(name, body = {}, session_token, context: nil)
         opts = {}

data/lib/parse/api/objects.rb

@@ -36,9 +36,9 @@ module Parse
       module ClassMethods
         # Get the API path for this class.
         #
-        # Both +className+ and +id+ are validated to prevent path-smuggling
+        # Both `className` and `id` are validated to prevent path-smuggling
         # attacks where an attacker-controlled string traverses to a
-        # different REST endpoint (e.g. +"../sessions/me"+) with whatever
+        # different REST endpoint (e.g. `"../sessions/me"`) with whatever
         # auth the outer request carries — typically the master key.
         #
         # @param className [String] the name of the Parse collection.
@@ -85,9 +85,9 @@ module Parse
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @param headers [Hash] additional HTTP headers to send with the request.
       # @param context [Hash, nil] an optional caller context forwarded as the
-      #   +X-Parse-Cloud-Context+ header. Parse Server maps it to
-      #   +req.info.context+ inside beforeSave/afterSave cloud triggers.
-      #   Omit or pass +nil+ to leave behavior unchanged.
+      #   `X-Parse-Cloud-Context` header. Parse Server maps it to
+      #   `req.info.context` inside beforeSave/afterSave cloud triggers.
+      #   Omit or pass `nil` to leave behavior unchanged.
       # @return [Parse::Response]
       def create_object(className, body = {}, headers: {}, context: nil, **opts)
         unless context.nil?
@@ -143,9 +143,9 @@ module Parse
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @param headers [Hash] additional HTTP headers to send with the request.
       # @param context [Hash, nil] an optional caller context forwarded as the
-      #   +X-Parse-Cloud-Context+ header. Parse Server maps it to
-      #   +req.info.context+ inside beforeSave/afterSave cloud triggers.
-      #   Omit or pass +nil+ to leave behavior unchanged.
+      #   `X-Parse-Cloud-Context` header. Parse Server maps it to
+      #   `req.info.context` inside beforeSave/afterSave cloud triggers.
+      #   Omit or pass `nil` to leave behavior unchanged.
       # @return [Parse::Response]
       def update_object(className, id, body = {}, headers: {}, context: nil, **opts)
         unless context.nil?

data/lib/parse/api/users.rb

@@ -108,9 +108,9 @@ module Parse
       #
       # Client-side rate limited on a per-email basis using the same
       # tracker that backs {#login} (entries are namespaced under a
-      # +pwreset:+ prefix so the two limiters don't collide on usernames
+      # `pwreset:` prefix so the two limiters don't collide on usernames
       # that happen to equal an email). Every request counts toward the
-      # backoff — Parse Server's +requestPasswordReset+ response does
+      # backoff — Parse Server's `requestPasswordReset` response does
       # not differentiate "email exists" from "email does not exist"
       # (and rightly so, to avoid account enumeration), so the SDK
       # cannot distinguish a legitimate retry from an attacker probing
@@ -212,23 +212,23 @@ module Parse
       # that the username + password combination is correct without producing a
       # new session token on success.
       #
-      # Uses the +POST /parse/verifyPassword+ endpoint (credentials in the request
-      # BODY, mirroring +login+) rather than the +GET+ form. Parse Server accepts
+      # Uses the `POST /parse/verifyPassword` endpoint (credentials in the request
+      # BODY, mirroring `login`) rather than the `GET` form. Parse Server accepts
       # both (same handler, neither master-key gated; the POST variant landed in
       # 7.1.0), but POST keeps the plaintext password out of the URL — and
-      # therefore out of server access logs, reverse-proxy logs, the +Referer+
+      # therefore out of server access logs, reverse-proxy logs, the `Referer`
       # header, and the SDK's URL-keyed response cache.
       #
       # On success Parse Server returns the user object (HTTP 200) with the same
-      # shape as a login response (minus +sessionToken+). On failure it returns a
+      # shape as a login response (minus `sessionToken`). On failure it returns a
       # 4xx with an error body, most commonly:
-      # - code 101 (+ERROR_OBJECT_NOT_FOUND+) for an unknown username or wrong password.
-      # - code 205 (+ERROR_EMAIL_NOT_FOUND+) when +preventLoginWithUnverifiedEmail+
+      # - code 101 (`ERROR_OBJECT_NOT_FOUND`) for an unknown username or wrong password.
+      # - code 205 (`ERROR_EMAIL_NOT_FOUND`) when `preventLoginWithUnverifiedEmail`
       #   is enabled and the account's email has not been verified.
       #
       # Client-side rate limited per username using the SAME bucket as {#login}
       # (bare username, no namespace) — failures across both credential oracles
-      # accumulate, so an attacker cannot bypass a +login+ lockout by pivoting to
+      # accumulate, so an attacker cannot bypass a `login` lockout by pivoting to
       # this endpoint. The trade-off: a run of failed step-up re-auth calls counts
       # toward (and can trigger) the primary login lockout for that username.
       # Client-side limiting is a convenience, not a boundary — the server is the

data/lib/parse/atlas_search/session.rb

@@ -11,46 +11,46 @@ module Parse
     #
     # Atlas Search runs aggregations directly against MongoDB and
     # therefore bypasses Parse Server's per-request ACL enforcement.
-    # To compile a +_rperm+ +$match+ stage (see {Parse::ACL.read_predicate})
+    # To compile a `_rperm` `$match` stage (see {Parse::ACL.read_predicate})
     # the caller needs to know two things about the requesting
     # session:
     #
-    #   1. The +_User.objectId+ that owns the session.
+    #   1. The `_User.objectId` that owns the session.
     #   2. The transitive upward closure of role names that user
     #      inherits permissions from (cf. {Parse::Role.all_for_user}).
     #
     # Both lookups can be expensive — token → user requires a
-    # +/users/me+ round-trip, and user → roles can require multiple
-    # +_Role+ queries to walk the inheritance graph. Both are cached
+    # `/users/me` round-trip, and user → roles can require multiple
+    # `_Role` queries to walk the inheritance graph. Both are cached
     # separately so a single agent turn that runs several Atlas Search
     # tools amortizes the cost.
     #
     # Two distinct caches:
     #
-    #   * +session_cache+: maps +session_token+ to +user_id+. Long
+    #   * `session_cache`: maps `session_token` to `user_id`. Long
     #     TTL (1 hour default), invalidation profile is logout. Apps
     #     that need sub-TTL revocation must call {.invalidate}
     #     explicitly from their logout path.
     #
-    #   * +role_cache+: maps +user_id+ to a +Set+ of role names. Short
+    #   * `role_cache`: maps `user_id` to a `Set` of role names. Short
     #     TTL (2 minutes default), invalidation profile is role-graph
     #     mutation. Stale role data here yields incorrect ACL
     #     decisions, so the default is conservatively short.
     #
     # The default cache implementation is process-local
-    # ({MemoryCache}) and guarded by a +Mutex+. Apps that need shared
+    # ({MemoryCache}) and guarded by a `Mutex`. Apps that need shared
     # cross-process caching (Redis, Memcached) may install a
     # replacement via {AtlasSearch.session_cache=} /
     # {AtlasSearch.role_cache=}; the replacement must respond to
-    # +get(key)+, +set(key, value, ttl:)+, and +invalidate(key)+.
+    # `get(key)`, `set(key, value, ttl:)`, and `invalidate(key)`.
     module Session
-      # Raised when a +session_token+ cannot be resolved — invalid
-      # token, expired session, or +/users/me+ returned an error.
+      # Raised when a `session_token` cannot be resolved — invalid
+      # token, expired session, or `/users/me` returned an error.
       # Atlas Search callers should treat this as a 401-equivalent.
       class InvalidSession < StandardError; end
 
       # Default cache: in-memory hash with per-entry TTL, guarded by a
-      # +Mutex+. Suitable for single-process apps. Apps running
+      # `Mutex`. Suitable for single-process apps. Apps running
       # multi-process (Puma workers, Sidekiq processes) get a per-
       # process cache — install a shared cache through
       # {AtlasSearch.session_cache=} for cross-process sharing.
@@ -61,7 +61,7 @@ module Parse
         end
 
         # @param key [String]
-        # @return [Object, nil] the cached value, or +nil+ when the key
+        # @return [Object, nil] the cached value, or `nil` when the key
         #   is missing or its TTL has elapsed. Expired entries are
         #   evicted lazily on read.
         def get(key)
@@ -97,15 +97,15 @@ module Parse
         end
       end
 
-      # Value returned by {Session.resolve}. +user_id+ is the
-      # +_User.objectId+ owning the session, or +nil+ for an anonymous
-      # caller. +role_names+ is a +Set+ of role names (no +role:+
+      # Value returned by {Session.resolve}. `user_id` is the
+      # `_User.objectId` owning the session, or `nil` for an anonymous
+      # caller. `role_names` is a `Set` of role names (no `role:`
       # prefix) the user inherits permissions from, computed via
       # {Parse::Role.all_for_user}.
       Resolved = Struct.new(:user_id, :role_names) do
-        # Build the canonical +_rperm+/+_wperm+ permission-string set
-        # for this session. Always includes +"*"+ (public). Includes
-        # +user_id+ when present. Includes +"role:#{name}"+ for each
+        # Build the canonical `_rperm`/`_wperm` permission-string set
+        # for this session. Always includes `"*"` (public). Includes
+        # `user_id` when present. Includes `"role:#{name}"` for each
         # inherited role.
         # @return [Array<String>]
         def permission_strings
@@ -115,33 +115,33 @@ module Parse
           out.uniq
         end
 
-        # @return [Boolean] +true+ for the anonymous-session case.
+        # @return [Boolean] `true` for the anonymous-session case.
         def anonymous?
           user_id.nil? || user_id.empty?
         end
       end
 
       class << self
-        # Resolve a +session_token+ to the requesting user and the
-        # transitive set of role names whose +role:NAME+ permission
-        # strings should be checked against +_rperm+.
+        # Resolve a `session_token` to the requesting user and the
+        # transitive set of role names whose `role:NAME` permission
+        # strings should be checked against `_rperm`.
         #
-        # +nil+ or empty +session_token+ → anonymous {Resolved} with
-        # +user_id: nil+ and an empty +role_names+ set. The caller
+        # `nil` or empty `session_token` → anonymous {Resolved} with
+        # `user_id: nil` and an empty `role_names` set. The caller
         # decides whether to refuse the request (the
-        # +require_session_token+ toggle on {Parse::AtlasSearch}) or
+        # `require_session_token` toggle on {Parse::AtlasSearch}) or
         # treat as public-only.
         #
         # Cache layering: token-to-user_id is checked first; on hit
-        # the slower +/users/me+ round-trip is skipped. User-to-roles
+        # the slower `/users/me` round-trip is skipped. User-to-roles
         # is then checked independently (a single user shared across
         # sessions amortizes the role lookup).
         #
-        # @param session_token [String, nil] the +X-Parse-Session-Token+
+        # @param session_token [String, nil] the `X-Parse-Session-Token`
         #   value from the requesting session.
         # @return [Resolved]
         # @raise [InvalidSession] when the token cannot be resolved by
-        #   +/users/me+ (404 / 209 invalid session token / 401).
+        #   `/users/me` (404 / 209 invalid session token / 401).
         def resolve(session_token)
           return Resolved.new(nil, Set.new) if session_token.nil? || session_token.to_s.empty?
 
@@ -150,12 +150,12 @@ module Parse
           Resolved.new(user_id, role_names)
         end
 
-        # Forget a +session_token+ entry from the session-token cache.
+        # Forget a `session_token` entry from the session-token cache.
         # Apps that revoke sessions out-of-band (logout, password
         # reset, admin revoke) should call this from the same path so
         # subsequent Atlas Search requests don't act on the stale
-        # +user_id+ mapping. The +role_names+ cache is keyed on
-        # +user_id+ and is not affected — call {.invalidate_user_roles}
+        # `user_id` mapping. The `role_names` cache is keyed on
+        # `user_id` and is not affected — call {.invalidate_user_roles}
         # to clear that separately.
         # @param session_token [String]
         def invalidate(session_token)
@@ -163,8 +163,8 @@ module Parse
           Parse::AtlasSearch.session_cache.invalidate(session_token.to_s)
         end
 
-        # Forget cached role membership for a +user_id+. Call after any
-        # +_Role.users+ mutation that affects this user (role grant /
+        # Forget cached role membership for a `user_id`. Call after any
+        # `_Role.users` mutation that affects this user (role grant /
         # revoke, role-graph reshape).
         # @param user_id [String]
         def invalidate_user_roles(user_id)
@@ -184,7 +184,7 @@ module Parse
 
         # @!visibility private
         # Resolve session_token → user_id via cache, falling through
-        # to +/users/me+. Raises {InvalidSession} on lookup failure;
+        # to `/users/me`. Raises {InvalidSession} on lookup failure;
         # the caller is responsible for refusing the request.
         def lookup_user_id(session_token)
           cache = Parse::AtlasSearch.session_cache