parse-stack-next 4.5.0 → 5.0.1

data/lib/parse/model/core/embed_managed.rb

@@ -0,0 +1,296 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../../embeddings"
+require_relative "../vector"
+
+module Parse
+  module Core
+    # Class-level `embed` macro for `:vector` properties.
+    #
+    # Lets a model declare which scalar fields feed into a managed
+    # embedding, and arranges for that embedding to be computed
+    # automatically on save whenever the source fields change.
+    #
+    # @example
+    #   class Document < Parse::Object
+    #     property :title, :string
+    #     property :body,  :string
+    #     property :body_embedding, :vector, dimensions: 1536, provider: :openai
+    #     embed :title, :body, into: :body_embedding
+    #   end
+    #
+    #   doc = Document.new(title: "hello", body: "world")
+    #   doc.save   # provider :openai is called once; body_embedding populated
+    #
+    # == Mechanics
+    #
+    # The class macro:
+    # 1. Validates that `into:` names a declared `:vector` property with
+    #    `provider:` metadata.
+    # 2. Auto-declares a `<into>_digest` `:string` sibling property
+    #    (override with `digest_field:`).
+    # 3. Registers a `before_save` callback that re-computes the
+    #    embedding whenever the SHA-256 of the concatenated source
+    #    fields differs from the stored digest. On first save the digest
+    #    is blank and the embedding is always populated. On a save where
+    #    no source field changed the digest matches and the callback is
+    #    a no-op (zero provider calls).
+    # 4. Prepends a guard module that raises {ProtectedFieldError} on
+    #    direct `body_embedding=` assignment from user code. The guard
+    #    lifts only inside the managed write path (the before_save
+    #    callback itself).
+    #
+    # Provider calls flow through {Parse::Embeddings.provider} — the
+    # provider is resolved by name at save time, so registering a
+    # provider can happen any time before the first save. Declaration
+    # never makes a network call.
+    #
+    # == Single vector per record (v5.0)
+    #
+    # `embed` produces exactly one vector per record. All declared
+    # source fields are concatenated (joined with "\n\n", blank values
+    # skipped) and sent to the provider as a single string. There is
+    # no built-in chunker in v5.0: long source text whose concatenation
+    # exceeds the provider's per-call token budget will be truncated
+    # provider-side, and the resulting vector will represent only the
+    # leading portion of the document.
+    #
+    # If your source text is long-form (full articles, long
+    # transcripts, multi-page PDFs), you have two options in v5.0:
+    #
+    # 1. Pre-chunk client-side and write each chunk as its own
+    #    Parse::Object record with its own `embed` declaration.
+    # 2. Maintain a dedicated `Chunk` subclass that belongs_to the
+    #    parent record, with `embed :content, into: :embedding` on the
+    #    chunk class itself.
+    #
+    # A built-in chunker + `semantic_search` agent tool are scheduled
+    # for v5.1.
+    module EmbedManaged
+      # Raised when user code tries to assign directly to a vector
+      # property that's managed by an {.embed} declaration. The intent
+      # is to make it impossible to silently desync the stored vector
+      # from the digest — every write goes through the digest-tracked
+      # recompute path.
+      class ProtectedFieldError < StandardError; end
+
+      # Raised at class-declaration time when `embed` is called with
+      # arguments that can't produce a valid managed vector — missing
+      # source fields, unknown target, target without `:vector` type, or
+      # `:vector` property without `provider:` metadata.
+      class InvalidEmbedDeclaration < ArgumentError; end
+
+      # Internal: name of the Thread-local key under which the managed
+      # writer marks the symbol of the field it is currently writing.
+      # The guard module's setter checks this key to permit a single
+      # field write; the guard is otherwise closed.
+      WRITER_KEY = :parse_embed_managed_writer
+
+      # Frozen value-object capturing one `embed` declaration. Stored on
+      # the owning class under `embed_directives[into]` and passed to
+      # {EmbedManaged.recompute_embedding!} from the per-class
+      # before_save callback.
+      EmbedDirective = Struct.new(
+        :sources, :into, :digest_field, :input_type, :provider_name,
+        keyword_init: true,
+      ) do
+        def freeze
+          sources.freeze
+          super
+        end
+      end
+
+      # @!visibility private
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Per-class registry of {EmbedDirective}s keyed by target vector
+        # property symbol. Read by tests and tooling; written only by
+        # {#embed}.
+        def embed_directives
+          @embed_directives ||= {}
+        end
+
+        # Declare a managed embedding. See {EmbedManaged} for the
+        # full description.
+        #
+        # @param source_fields [Array<Symbol>] one or more scalar
+        #   property names whose values are concatenated (joined with
+        #   "\n\n", `nil` skipped) to form the embed input.
+        # @param into [Symbol] the `:vector` property to populate.
+        #   Must already be declared with `provider:` metadata.
+        # @param input_type [Symbol] forwarded to
+        #   {Parse::Embeddings::Provider#embed_text}. Defaults to
+        #   `:search_document` (the write-side counterpart to
+        #   `find_similar(text:)`'s `:search_query`).
+        # @param digest_field [Symbol, nil] override for the digest
+        #   sibling property. Defaults to `:"#{into}_digest"`. Auto-
+        #   declared as `:string` if not already declared.
+        # @return [Symbol] the target vector field name.
+        # @raise [InvalidEmbedDeclaration] on declaration-time misuse.
+        def embed(*source_fields, into:, input_type: :search_document, digest_field: nil)
+          if source_fields.empty?
+            raise InvalidEmbedDeclaration,
+                  "#{self}.embed: at least one source field is required."
+          end
+          into = into.to_sym
+          unless vector_properties.key?(into)
+            raise InvalidEmbedDeclaration,
+                  "#{self}.embed: `into: :#{into}` is not a declared :vector property " \
+                  "(declared :vector fields: #{vector_properties.keys.inspect})."
+          end
+          provider_name = vector_properties.dig(into, :provider)
+          if provider_name.nil?
+            raise InvalidEmbedDeclaration,
+                  "#{self}.embed: `into: :#{into}` has no `provider:` declared on its :vector " \
+                  "property. Add `provider: :openai` (or another registered name) to the " \
+                  "property declaration."
+          end
+          sources = source_fields.map(&:to_sym)
+          missing = sources.reject { |f| fields.key?(f) }
+          unless missing.empty?
+            raise InvalidEmbedDeclaration,
+                  "#{self}.embed: source fields #{missing.inspect} are not declared on this class."
+          end
+
+          digest_field = (digest_field || :"#{into}_digest").to_sym
+          unless fields.key?(digest_field)
+            property digest_field, :string
+          end
+
+          directive = EmbedDirective.new(
+            sources: sources,
+            into: into,
+            digest_field: digest_field,
+            input_type: input_type,
+            provider_name: provider_name,
+          ).freeze
+          embed_directives[into] = directive
+
+          callback_method = :"_auto_embed_#{into}!"
+          define_method(callback_method) do
+            Parse::Core::EmbedManaged.recompute_embedding!(self, directive)
+          end
+
+          already_registered = _save_callbacks.any? do |cb|
+            cb.kind == :before && (cb.filter.to_sym rescue cb.filter) == callback_method
+          end
+          before_save callback_method unless already_registered
+
+          install_embed_writer_guard!(into, sources)
+
+          into
+        end
+
+        # @!visibility private
+        # Prepend a module that intercepts the public `<into>=` setter
+        # and raises {ProtectedFieldError} unless the current thread has
+        # marked itself as the managed writer for this field.
+        def install_embed_writer_guard!(into, sources)
+          setter = :"#{into}="
+          guard = Module.new
+          field_sym = into
+          source_list = sources
+          guard.module_eval do
+            define_method(setter) do |val|
+              if Thread.current[Parse::Core::EmbedManaged::WRITER_KEY] == field_sym
+                super(val)
+              else
+                raise Parse::Core::EmbedManaged::ProtectedFieldError,
+                      "#{self.class}##{field_sym} is managed by `embed` and cannot be " \
+                      "assigned directly. Update source fields #{source_list.inspect} " \
+                      "and save; the embedding will be recomputed automatically."
+              end
+            end
+          end
+          prepend(guard)
+        end
+      end
+
+      # @!visibility private
+      # Run the managed-write path with the writer guard lifted for
+      # exactly one field. Restores the prior value of the Thread-local
+      # on exit so nested calls (and unrelated callers on the same
+      # thread) are unaffected.
+      def self.with_writer(field)
+        prev = Thread.current[WRITER_KEY]
+        Thread.current[WRITER_KEY] = field
+        yield
+      ensure
+        Thread.current[WRITER_KEY] = prev
+      end
+
+      # @!visibility private
+      # before_save body. Computes the SHA-256 digest of the
+      # concatenated source-field values. If the digest matches the
+      # stored sibling AND the target vector is already populated, the
+      # method returns without contacting the provider. Otherwise it
+      # calls the provider, validates the response shape, wraps the
+      # vector, and writes both the vector and digest under the writer
+      # guard (so the public setters' dirty-tracking fires).
+      def self.recompute_embedding!(record, directive)
+        text = build_source_text(record, directive.sources)
+        stored_digest = record.public_send(directive.digest_field)
+        target_present = !record.public_send(directive.into).nil?
+
+        if text.empty?
+          if target_present || !stored_digest.nil?
+            with_writer(directive.into) do
+              record.public_send(:"#{directive.into}=", nil)
+            end
+            record.public_send(:"#{directive.digest_field}=", nil)
+          end
+          return
+        end
+
+        digest = digest_for(text)
+        return if stored_digest == digest && target_present
+
+        provider = Parse::Embeddings.provider(directive.provider_name)
+        vectors = provider.embed_text([text], input_type: directive.input_type)
+        unless vectors.is_a?(Array) && vectors.length == 1 && vectors.first.is_a?(Array)
+          raise Parse::Embeddings::InvalidResponseError,
+                "Parse::Core::EmbedManaged (#{record.class}##{directive.into}): provider " \
+                "#{directive.provider_name.inspect} did not return a single vector " \
+                "(got #{vectors.inspect[0, 80]})."
+        end
+        vector = Parse::Vector.new(vectors.first)
+        expected_dims = record.class.vector_properties.dig(directive.into, :dimensions)
+        if expected_dims && vector.dimensions != expected_dims
+          raise Parse::Embeddings::InvalidResponseError,
+                "Parse::Core::EmbedManaged (#{record.class}##{directive.into}): provider " \
+                "#{directive.provider_name.inspect} returned #{vector.dimensions}-dim vector " \
+                "but property declares dimensions: #{expected_dims}."
+        end
+
+        with_writer(directive.into) do
+          record.public_send(:"#{directive.into}=", vector)
+        end
+        record.public_send(:"#{directive.digest_field}=", digest)
+      end
+
+      # @!visibility private
+      # Concatenate source-field string values. `nil` and blank entries
+      # are skipped; remaining values are joined with a double newline.
+      # If every source is blank the result is the empty string, which
+      # the caller treats as "clear the embedding".
+      def self.build_source_text(record, sources)
+        sources.map { |f| record.public_send(f).to_s }
+               .reject(&:empty?)
+               .join("\n\n")
+      end
+
+      # @!visibility private
+      # Truncated SHA-256 hex of the source text. 32 hex chars (128
+      # bits) is plenty for a non-cryptographic change detector and
+      # keeps the digest sibling field compact.
+      def self.digest_for(text)
+        Digest::SHA256.hexdigest(text)[0, 32]
+      end
+    end
+  end
+end

data/lib/parse/model/core/fetching.rb

@@ -139,14 +139,14 @@ module Parse
         # If we successfully fetched data, ensure the object is not marked as deleted
         @_deleted = false
 
-        # Capture dirty fields and their local values BEFORE applying server data
+        # Post dirty fields and their local values BEFORE applying server data
         dirty_fields = {}
         if respond_to?(:changed)
           begin
             changed_attrs = changed
             if changed_attrs.respond_to?(:each)
               changed_attrs.each do |attr|
-                # Only capture if object responds to the attribute getter
+                # Only post if object responds to the attribute getter
                 if respond_to?(attr)
                   begin
                     dirty_fields[attr.to_sym] = send(attr)
@@ -436,7 +436,7 @@ module Parse
                       !Parse::Properties::BASE_KEYS.include?(key) &&
                       respond_to?(:fetch)
 
-        # Capture caller stack BEFORE mutex for better error tracebacks
+        # Post caller stack BEFORE mutex for better error tracebacks
         # Filter out internal parse-stack frames to show where user code accessed the field
         caller_stack = caller.reject { |frame| frame.include?("/lib/parse/") }
 
@@ -487,7 +487,7 @@ module Parse
       # Prepares object for dirty tracking by fetching if needed.
       # Must be called BEFORE will_change! to prevent autofetch from wiping dirty state.
       #
-      # When will_change! captures the old value by calling the getter, it may trigger
+      # When will_change! posts the old value by calling the getter, it may trigger
       # autofetch if the object is a pointer. That autofetch calls clear_changes! which
       # wipes the dirty tracking state will_change! is trying to set up.
       #

data/lib/parse/model/core/indexing.rb

@@ -115,36 +115,50 @@ module Parse
       # `Parse::Role.users`, the reverse direction is often the
       # heavier-used index.
       #
-      # Uniqueness is NOT supported on `mongo_relation_index` — a unique
-      # single-direction index on a `has_many :through => :relation`
-      # field is semantically broken (it would say each owner can hold
-      # at most one related, contradicting `has_many`). If you want to
-      # enforce no-duplicate-pair membership, declare a compound unique
-      # index directly via `Parse::MongoDB.create_index` or a later
-      # extension to this DSL.
+      # Uniqueness on a *single-direction* relation index is NOT
+      # supported — `unique: true` on just `owningId` (or just
+      # `relatedId`) would assert each owner can hold at most one
+      # related, contradicting `has_many`. That mistake is rejected at
+      # declaration time.
       #
-      # @example Canonical case — role membership
+      # `dedup: true` is semantically different and IS supported: it
+      # registers a compound `{owningId: 1, relatedId: 1}` unique index
+      # on the join collection. The compound key prevents duplicate
+      # `(owner, related)` pair rows from accumulating (a real failure
+      # mode under concurrent `.add` calls on a Parse Relation), without
+      # constraining how many distinct relateds an owner may hold or
+      # vice versa. Default off — the index buys correctness at the
+      # cost of a write-time uniqueness check on every relation insert,
+      # and existing collections with duplicate pairs will fail the
+      # migrator's apply step until reconciled.
+      #
+      # @example Canonical case — role membership with dedup
       #   class Parse::Role < Parse::Object
       #     has_many :users, through: :relation
-      #     mongo_relation_index :users, bidirectional: true
+      #     mongo_relation_index :users, bidirectional: true, dedup: true
       #     # creates: _Join:users:_Role { owningId: 1 }
       #     #         _Join:users:_Role { relatedId: 1 }
+      #     #         _Join:users:_Role { owningId: 1, relatedId: 1 } unique
       #   end
       #
       # @param field [Symbol] the relation field name (must be declared
       #   via `has_many :field, through: :relation`)
       # @param bidirectional [Boolean] when true, register two
       #   declarations — one each for owningId and relatedId
+      # @param dedup [Boolean] when true, also register a compound
+      #   `{owningId: 1, relatedId: 1}` unique index that prevents
+      #   duplicate-pair membership rows
+      # @param unique [Boolean] rejected — see above
       # @raise [ArgumentError] when `field` is not a declared relation
-      #   or `unique:` is passed (not supported on relation indexes)
+      #   or `unique:` is passed
       # @return [Array<Hash>] the registered declarations
-      def mongo_relation_index(field, bidirectional: false, unique: false)
+      def mongo_relation_index(field, bidirectional: false, dedup: false, unique: false)
         if unique
           raise ArgumentError,
                 "#{self}.mongo_relation_index does not support unique: — uniqueness on " \
-                "a single-direction relation column breaks has_many semantics. For no-" \
-                "duplicate-pair membership, declare a compound unique index directly " \
-                "via Parse::MongoDB.create_index."
+                "a single-direction relation column breaks has_many semantics. Use " \
+                "`dedup: true` for a compound `{owningId, relatedId}` unique index that " \
+                "prevents duplicate-pair membership without constraining cardinality."
         end
         field = field.to_sym
         unless respond_to?(:relations) && relations.key?(field)
@@ -155,6 +169,9 @@ module Parse
         join_collection = "_Join:#{field}:#{parse_class}"
         decls = [register_relation_index(join_collection, "owningId", source: field)]
         decls << register_relation_index(join_collection, "relatedId", source: field) if bidirectional
+        if dedup
+          decls << register_relation_dedup_index(join_collection, source: field)
+        end
         decls
       end
 
@@ -242,6 +259,28 @@ module Parse
         decl
       end
 
+      # Register the compound `{owningId: 1, relatedId: 1}` unique index
+      # on a relation join collection — the dedup form of
+      # `mongo_relation_index`. Compound uniqueness on both columns
+      # together is the *correctness* form: it forbids duplicate
+      # `(owner, related)` pair rows from accumulating without
+      # constraining how many distinct relateds an owner may hold.
+      # That is semantically different from `unique:` on a single
+      # column (which `mongo_relation_index` continues to reject).
+      def register_relation_dedup_index(collection, source:)
+        decl = {
+          keys:         { "owningId" => 1, "relatedId" => 1 }.freeze,
+          options:      { unique: true }.freeze,
+          declared_for: [source].freeze,
+          collection:   collection,
+        }.freeze
+        if mongo_index_declarations.any? { |d| d[:keys] == decl[:keys] && d[:options] == decl[:options] && d[:collection] == collection }
+          return decl
+        end
+        mongo_index_declarations << decl
+        decl
+      end
+
       # Translate a property symbol to the wire-format column name a
       # MongoDB index must reference. Pointer fields (declared via
       # `belongs_to`) live in Mongo at `_p_<field>` and the SDK already

data/lib/parse/model/core/parse_reference.rb

@@ -10,8 +10,8 @@ module Parse
     # subclasses. When `parse_reference` is declared on a class, every newly-
     # created instance gets a string field auto-populated with the canonical
     # `"ClassName$objectId"` form via an `after_create` callback. The value
-    # mirrors Parse Server's internal pointer-column format (`_p_team` ->
-    # `"Team$xyz"`), which makes direct MongoDB queries, `$lookup` joins, and
+    # mirrors Parse Server's internal pointer-column format (`_p_workspace` ->
+    # `"Workspace$xyz"`), which makes direct MongoDB queries, `$lookup` joins, and
     # cross-class analytics trivial: a single equality match on one column.
     #
     # Mechanics:
@@ -131,7 +131,7 @@ module Parse
       extend ActiveSupport::Concern
 
       # The separator between class name and object id. Matches Parse Server's
-      # own pointer-column format (e.g. `_p_team = "Team$abcd1234"`).
+      # own pointer-column format (e.g. `_p_workspace = "Workspace$abcd1234"`).
       SEPARATOR = "$".freeze
 
       # Length of a Parse Server objectId. Matches the format the server itself

data/lib/parse/model/core/properties.rb

@@ -19,7 +19,7 @@ module Parse
   # supported in Parse and mapping them between their remote names with their local ruby named attributes.
   module Properties
     # These are the base types supported by Parse.
-    TYPES = [:string, :relation, :integer, :float, :boolean, :date, :array, :file, :geopoint, :polygon, :bytes, :object, :acl, :timezone, :phone, :email].freeze
+    TYPES = [:string, :relation, :integer, :float, :boolean, :date, :array, :file, :geopoint, :polygon, :bytes, :object, :acl, :timezone, :phone, :email, :vector].freeze
     # These are the base mappings of the remote field name types.
     BASE = { objectId: :string, createdAt: :date, updatedAt: :date, ACL: :acl }.freeze
     # The list of properties that are part of all objects
@@ -135,6 +135,18 @@ module Parse
         @property_enum_descriptions ||= {}
       end
 
+      # @return [Hash] per-property metadata for `:vector`-typed fields.
+      # Maps property names (symbols) to a frozen options hash:
+      # `{ dimensions: Integer, provider: Symbol, model: String, similarity: Symbol }`.
+      # `dimensions:` is required; the rest are optional and only carry
+      # meaning for the embedding provider plumbing layered above this
+      # type. Consumed by `Parse::Embeddings` and
+      # `Parse::AtlasSearch::IndexCatalog` to resolve which vector index
+      # to query for a given field.
+      def vector_properties
+        @vector_properties ||= {}
+      end
+
       # Set the property fields for this class.
       # @return [Hash]
       def attributes=(hash)
@@ -318,6 +330,44 @@ module Parse
           end # validates_each
         end # data_type == :phone
 
+        # vector datatypes capture per-property embedding metadata
+        # (dimensions, provider, model, similarity) and validate that
+        # any assigned value matches the declared `dimensions:`.
+        # `dimensions:` is required at declaration time — the field
+        # cannot be safely indexed or compared against a query vector
+        # without it.
+        if data_type == :vector
+          dims = opts[:dimensions] || opts[:dims]
+          unless dims.is_a?(Integer) && dims > 0
+            raise ArgumentError,
+                  "Property #{self}##{key} :vector requires `dimensions:` as a positive Integer."
+          end
+          if dims > Parse::Vector::MAX_DIMENSIONS
+            raise ArgumentError,
+                  "Property #{self}##{key} :vector dimensions #{dims} exceeds max " \
+                  "#{Parse::Vector::MAX_DIMENSIONS}."
+          end
+          vector_properties[key] = {
+            dimensions: dims,
+            provider: opts[:provider],
+            model: opts[:model],
+            similarity: opts[:similarity],
+          }.freeze
+
+          validates_each key do |record, attribute, value|
+            next if value.nil?
+            unless value.is_a?(Parse::Vector)
+              record.errors.add(attribute, "field :#{attribute} must be a Parse::Vector.")
+            else
+              expected = record.class.vector_properties.dig(attribute, :dimensions)
+              if expected && value.dimensions != expected
+                record.errors.add(attribute,
+                  "field :#{attribute} expected #{expected} dimensions, got #{value.dimensions}.")
+              end
+            end
+          end # validates_each
+        end # data_type == :vector
+
         # email datatypes validate email format.
         if data_type == :email
           validates_each key do |record, attribute, value|
@@ -794,6 +844,25 @@ module Parse
         val = Parse::Phone.new(val) if val.present?
       when :email
         val = Parse::Email.new(val) if val.present?
+      when :vector
+        # nil/blank → unset; coerce Arrays (and pass-through Parse::Vector)
+        # to a Parse::Vector, which validates that every element is a
+        # finite Numeric. Dimension mismatch is reported via
+        # validates_each so callers can rescue ActiveModel::ValidationError
+        # at save time rather than at every assignment; raising here
+        # would break partial hydration where the dimension class-level
+        # declaration may not yet be loaded.
+        if val.nil?
+          val = nil
+        elsif val.is_a?(Parse::Vector)
+          val = val
+        elsif val.is_a?(Array)
+          val = Parse::Vector.new(val)
+        else
+          raise ArgumentError,
+                "Property #{self.class}##{key} :vector requires an Array or Parse::Vector " \
+                "(got #{val.class})."
+        end
       else
         # You can provide a specific class instead of a symbol format
         if data_type.respond_to?(:typecast)

data/lib/parse/model/core/querying.rb

@@ -215,6 +215,21 @@ module Parse
         prepared_query.results
       end
 
+      # Convenience wrapper around {.all} that runs the query under a
+      # caller-supplied session token. Equivalent to passing
+      # `session_token:` in the constraints hash, surfaced as a named
+      # kwarg so client-mode callers don't have to remember the
+      # constraint-key form. Returns nil if `token` is blank.
+      # @param token [String, Parse::User, Parse::Session] session token,
+      #   user instance, or session instance.
+      # @param constraints (see .all)
+      # @return [Array<Parse::Object>]
+      def all_as(token, constraints = { limit: :max }, &block)
+        tok = token.respond_to?(:session_token) ? token.session_token : token
+        return nil if tok.nil? || tok.to_s.empty?
+        all(constraints.merge(session_token: tok), &block)
+      end
+
       # Returns the first item matching the constraint.
       # @overload first(count = 1)
       #  @param count [Interger] The number of items to return.
@@ -239,6 +254,23 @@ module Parse
         return res.first fetch_count
       end
 
+      # Convenience wrapper around {.first} that runs the query under a
+      # caller-supplied session token.
+      # @param token [String, Parse::User, Parse::Session] session token,
+      #   user instance, or session instance.
+      # @param constraints (see .first)
+      # @return [Parse::Object, Array<Parse::Object>, nil]
+      def first_as(token, constraints = {})
+        tok = token.respond_to?(:session_token) ? token.session_token : token
+        return nil if tok.nil? || tok.to_s.empty?
+        if constraints.is_a?(Numeric)
+          # `first(2)` shape — surface kwarg via a synthetic constraints hash
+          first({ limit: constraints.to_i, session_token: tok })
+        else
+          first(constraints.merge(session_token: tok))
+        end
+      end
+
       # Returns the most recently created object (ordered by created_at descending).
       # @overload latest(count = 1)
       #  @param count [Integer] The number of items to return.
@@ -407,6 +439,13 @@ module Parse
       # @see Parse::LiveQuery::Subscription
       # @see Parse::Query#subscribe
       def subscribe(where: {}, fields: nil, session_token: nil, client: nil)
+        # Fall through to the ambient set by `Parse.with_session` / `Parse.login`
+        # so a caller wrapping a region with `with_session(user) { Klass.subscribe ... }`
+        # gets an ACL-aware subscription without re-threading the token.
+        if session_token.nil?
+          ambient = Parse.current_session_token
+          session_token = ambient if ambient.is_a?(String) && !ambient.empty?
+        end
         query(where).subscribe(fields: fields, session_token: session_token, client: client)
       end
 
@@ -430,7 +469,7 @@ module Parse
       #   - false - completely bypass cache (no read or write)
       # @return [Parse::Object] if only one id was provided as a parameter.
       # @return [Array<Parse::Object>] if more than one id was provided as a parameter.
-      def find(*parse_ids, type: :parallel, compact: true, cache: nil)
+      def find(*parse_ids, type: :parallel, compact: true, cache: nil, session_token: nil, use_master_key: nil)
         # flatten the list of Object ids.
         parse_ids.flatten!
         parse_ids.compact!
@@ -446,11 +485,28 @@ module Parse
 
         # Extract cache option for client requests
         client_opts = { cache: cache }
+        # Forward session-token / use_master_key when supplied so client-mode
+        # callers can scope a `.find` to a logged-in user without dropping
+        # down to the raw `client.fetch_object` form.
+        client_opts[:session_token]  = session_token  unless session_token.nil?
+        client_opts[:use_master_key] = use_master_key unless use_master_key.nil?
+        # The parallel path spawns worker threads via `Parallel.map`. Worker
+        # threads don't inherit fiber-local storage from the calling thread,
+        # so `Parse.current_session_token` resolved inside the worker would
+        # be nil even when the caller is inside a `Parse.with_session(...)`
+        # block. Snapshot the ambient here (in the calling thread) and pass
+        # it explicitly so each worker sends the right auth.
+        if !client_opts.key?(:session_token)
+          ambient = Parse.current_session_token
+          client_opts[:session_token] = ambient if ambient.is_a?(String) && !ambient.empty?
+        end
 
         if type == :batch
           # use a .in query with the given id as a list
           query = self.class.query(:id.in => parse_ids)
           query.cache = cache
+          query.session_token = session_token unless session_token.nil?
+          query.use_master_key = use_master_key unless use_master_key.nil?
           results = query.results
         else
           # use Parallel to make multiple threaded requests for finding these objects.