parse-stack-next 5.1.1 → 5.2.0

data/lib/parse/retrieval/retriever.rb

@@ -0,0 +1,274 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "chunker"
+require_relative "chunk"
+
+module Parse
+  # Retrieval-augmented-generation (RAG) helpers. `Parse::RAG` is a
+  # discoverability alias for this module.
+  #
+  # {.retrieve} is the agent-agnostic core: it embeds a natural-language
+  # query, runs Atlas `$vectorSearch` through the existing
+  # `Class.find_similar` (which enforces ACL/CLP mongo-direct), then
+  # splits each retrieved document's text field into scored
+  # {Parse::Retrieval::Chunk}s for presentation.
+  #
+  # The agent-facing `semantic_search` tool (see
+  # `lib/parse/retrieval/agent_tool.rb`) wraps {.retrieve} with the
+  # agent security envelope (tenant scope, `field_allowlist` projection,
+  # score quantization).
+  #
+  # == ACL model
+  #
+  # {.retrieve} does NOT implement a REST "two-stage" re-query. The
+  # vector path is mongo-direct only (Parse Server's REST `/aggregate`
+  # is master-key-only and bypasses ACL — see the project notes), and
+  # `acl_user:` / `acl_role:` scopes have no REST equivalent. ACL is
+  # enforced inside `find_similar` via a post-`$vectorSearch` `_rperm`
+  # `$match`. Scope kwargs (`session_token:` / `acl_user:` /
+  # `acl_role:` / `master:`) pass straight through `**scope_opts`.
+  module Retrieval
+    # Raised when a tenant-scope value conflicts with a caller-supplied
+    # `vector_filter` constraint on the same field — a scope-spoofing
+    # attempt. Mirrors the agent layer's tenant-scope refusal.
+    class TenantScopeConflict < ArgumentError; end
+
+    # Raised when the text field to chunk cannot be inferred from the
+    # class's `embed` declarations and was not passed explicitly.
+    class AmbiguousTextField < ArgumentError; end
+
+    module_function
+
+    # Recursively refuse any underscore-prefixed key, at any depth, in a
+    # caller-supplied filter. This is distinct from (and stricter than)
+    # the agent layer's flat `validate_keys!`: a Mongo-style filter is a
+    # nested structure, and an underscore key buried inside `$or` /
+    # `$elemMatch` / a hash value could clobber tenant scope or reach a
+    # reserved column (`_rperm`, `_p_*`, `_auth_data_*`). The walk is
+    # unconditional — it does not special-case operators.
+    #
+    # @param obj [Object] a filter Hash/Array (or anything; scalars pass).
+    # @param path [Array<String>] internal — accumulates the key path for
+    #   the error message.
+    # @raise [ArgumentError] on any `_`-prefixed key.
+    def assert_no_underscore_keys!(obj, path = [])
+      case obj
+      when Hash
+        obj.each do |k, v|
+          ks = k.to_s
+          if ks.start_with?("_")
+            raise ArgumentError,
+                  "filter key '#{(path + [ks]).join(".")}' is reserved (underscore-prefixed)."
+          end
+          assert_no_underscore_keys!(v, path + [ks])
+        end
+      when Array
+        obj.each_with_index { |v, i| assert_no_underscore_keys!(v, path + ["[#{i}]"]) }
+      end
+      obj
+    end
+
+    # Retrieve and chunk documents semantically similar to `query`.
+    #
+    # @param query [String] natural-language query.
+    # @param klass [Class, String] a Parse::Object subclass (or its
+    #   class name) declaring a `:vector` property. `class:` is accepted
+    #   as an alias.
+    # @param field [Symbol, nil] the `:vector` property to search.
+    #   Auto-resolved by `find_similar` when the class has exactly one.
+    # @param text_field [Symbol, nil] the text property to chunk for
+    #   presentation. Defaults to the sole text source of the class's
+    #   `embed` declaration; raises {AmbiguousTextField} when it can't be
+    #   inferred.
+    # @param k [Integer] number of documents to retrieve. Default 10.
+    # @param filter [Hash, nil] post-`$vectorSearch` `$match` filter.
+    # @param vector_filter [Hash, nil] Atlas-native pre-search filter.
+    # @param chunker [#chunk_with_meta, #chunk, nil] chunking strategy.
+    #   Defaults to {Chunker::FixedSizeOverlap}.
+    # @param tenant_scope [Hash, nil] `{ field:, value: }` merged into
+    #   `vector_filter` (closing the cross-tenant existence side
+    #   channel) — not just a post-stage match.
+    # @param score_quantize [Boolean] round scores to 1 decimal (limits
+    #   membership-inference probing in non-admin contexts).
+    # @param source_transform [#call, nil] optional callable applied to
+    #   each raw source record before it is stored on a Chunk. The agent
+    #   tool injects tenant-scope assertion + `field_allowlist`
+    #   projection here; a `StandardError` raised by the callable
+    #   propagates and aborts the whole call (fail-closed). Kept as an
+    #   injection point so this model-layer method stays free of any
+    #   agent-layer dependency.
+    # @param hybrid [Object, nil] reserved — raises {NotImplementedError}
+    #   if truthy. Hybrid (vector + lexical) retrieval lands in a later
+    #   release; the kwarg locks the API shape now.
+    # @param rerank [Object, nil] reserved — raises {NotImplementedError}
+    #   if non-nil. Cross-encoder rerank lands in a later release.
+    # @param scope_opts [Hash] ACL/CLP scope kwargs forwarded verbatim to
+    #   `find_similar`: `session_token:` / `acl_user:` / `acl_role:` /
+    #   `master:`.
+    # @return [Array<Parse::Retrieval::Chunk>] descending by score; chunk
+    #   order within a document is positional.
+    def retrieve(query:, klass: nil, field: nil, text_field: nil, k: 10,
+                 filter: nil, vector_filter: nil, chunker: nil,
+                 tenant_scope: nil, score_quantize: false,
+                 source_transform: nil, hybrid: nil, rerank: nil,
+                 **scope_opts)
+      raise NotImplementedError,
+            "Parse::Retrieval.retrieve: `hybrid:` is reserved for a future release." if hybrid
+      raise NotImplementedError,
+            "Parse::Retrieval.retrieve: `rerank:` is reserved for a future release." if rerank
+
+      # `class:` alias (reserved word — arrives via **scope_opts).
+      klass ||= scope_opts.delete(:class)
+      klass = resolve_class!(klass)
+
+      unless query.is_a?(String) && !query.strip.empty?
+        raise ArgumentError, "Parse::Retrieval.retrieve: `query:` must be a non-empty String."
+      end
+
+      resolved_text_field = (text_field || infer_text_field!(klass)).to_sym
+      merged_vector_filter = fold_tenant_scope(klass, vector_filter, tenant_scope)
+      chunker ||= default_chunker
+
+      raw_hits = klass.find_similar(
+        text: query,
+        k: k,
+        field: field,
+        filter: filter,
+        vector_filter: merged_vector_filter,
+        raw: true,
+        **scope_opts,
+      )
+      return [] if raw_hits.nil? || raw_hits.empty?
+
+      text_wire = wire_name(klass, resolved_text_field)
+
+      raw_hits.flat_map do |doc|
+        build_chunks_for(doc, klass, text_wire, score_quantize, source_transform, chunker)
+      end
+    end
+
+    # @!visibility private
+    def resolve_class!(klass)
+      resolved =
+        case klass
+        when nil
+          nil
+        when Class
+          klass
+        else
+          Parse::Model.find_class(klass.to_s)
+        end
+      unless resolved.is_a?(Class) && resolved.respond_to?(:find_similar)
+        raise ArgumentError,
+              "Parse::Retrieval.retrieve: `klass:`/`class:` must be a Parse::Object " \
+              "subclass with a :vector property (got #{klass.inspect})."
+      end
+      resolved
+    end
+
+    # @!visibility private
+    # Infer the text field to chunk from the class's `embed` directives:
+    # the sole text (non-image) source field. Raises when zero or more
+    # than one candidate exists — the caller must then pass `text_field:`.
+    def infer_text_field!(klass)
+      directives = klass.respond_to?(:embed_directives) ? klass.embed_directives.values : []
+      sources = directives.reject { |d| d.respond_to?(:image?) && d.image? }
+                          .flat_map(&:sources).uniq
+      return sources.first if sources.length == 1
+      raise AmbiguousTextField,
+            "Parse::Retrieval.retrieve: cannot infer the text field to chunk for " \
+            "#{klass} (candidates: #{sources.inspect}); pass `text_field:` explicitly."
+    end
+
+    # @!visibility private
+    def default_chunker
+      Chunker::FixedSizeOverlap.new(size: 800, overlap: 100)
+    end
+
+    # @!visibility private
+    # Merge the tenant scope into the Atlas pre-search filter using the
+    # field's wire/storage column name. A pre-existing constraint on the
+    # same field with a different value is a spoof attempt and is refused.
+    def fold_tenant_scope(klass, vector_filter, tenant_scope)
+      return vector_filter if tenant_scope.nil?
+      field = tenant_scope[:field] || tenant_scope["field"]
+      value = tenant_scope.key?(:value) ? tenant_scope[:value] : tenant_scope["value"]
+      return vector_filter if field.nil?
+
+      wire = wire_name(klass, field)
+      base = vector_filter ? vector_filter.dup : {}
+      existing_key = base.keys.find { |k| k.to_s == wire }
+      if existing_key && base[existing_key] != value
+        raise TenantScopeConflict,
+              "Parse::Retrieval.retrieve: vector_filter pins #{wire.inspect} to " \
+              "#{base[existing_key].inspect} but the tenant scope requires #{value.inspect}."
+      end
+      base[wire] = value
+      base
+    end
+
+    # @!visibility private
+    # Ruby property symbol -> wire/storage column name. Prefers the
+    # class's explicit field_map alias; falls back to lowerCamelCase
+    # columnization. Matches the resolution MetadataRegistry uses.
+    def wire_name(klass, field)
+      sym = field.to_sym
+      fmap = klass.respond_to?(:field_map) ? klass.field_map : {}
+      mapped = fmap[sym]
+      (mapped || sym.to_s.columnize).to_s
+    end
+
+    # @!visibility private
+    def fetch_field(doc, wire, sym)
+      return doc[wire] if doc.key?(wire)
+      return doc[wire.to_sym] if doc.key?(wire.to_sym)
+      return doc[sym.to_s] if doc.key?(sym.to_s)
+      doc[sym]
+    end
+
+    # @!visibility private
+    def build_chunks_for(doc, klass, text_wire, score_quantize, source_transform, chunker)
+      object_id = (doc["_id"] || doc[:_id] || doc["objectId"] || doc[:objectId]).to_s
+      raw_score = doc["_vscore"] || doc[:_vscore]
+      score = quantize_score(raw_score, score_quantize)
+
+      text = fetch_field(doc, text_wire, text_wire)
+      meta = chunker.respond_to?(:chunk_with_meta) ? chunker.chunk_with_meta(text) : nil
+      chunks = meta ? meta[:chunks] : Array(chunker.chunk(text))
+      truncated = meta ? meta[:truncated] : false
+      # A document that matched on its vector but carries no presentation
+      # text yields no chunks (skipped, not an empty-content chunk).
+      return [] if chunks.empty?
+
+      source = source_transform ? source_transform.call(doc) : doc
+      count = chunks.length
+      chunks.each_with_index.map do |content, idx|
+        Chunk.new(
+          id: "#{object_id}##{idx}",
+          content: content,
+          score: score,
+          source: source,
+          metadata: {
+            chunk_index: idx,
+            chunk_count: count,
+            chunks_truncated: truncated,
+            object_id: object_id,
+            class: klass.parse_class,
+          },
+        )
+      end
+    end
+
+    # @!visibility private
+    def quantize_score(score, quantize)
+      return score if score.nil?
+      f = score.to_f
+      quantize ? ((f * 10).round / 10.0) : f
+    end
+  end
+
+  # Discoverability alias. "RAG" ages badly as a term; `Retrieval` is
+  # the canonical name.
+  RAG = Retrieval
+end

data/lib/parse/retrieval.rb

@@ -0,0 +1,10 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Parse::Retrieval — retrieval-augmented-generation (RAG) helpers.
+#
+# Entry point that loads the chunker, the {Parse::Retrieval::Chunk}
+# value object, and the {Parse::Retrieval.retrieve} core. The
+# `semantic_search` agent tool (which depends on the agent layer) is
+# loaded separately from `lib/parse/agent.rb`.
+require_relative "retrieval/retriever"

data/lib/parse/schema.rb

@@ -231,16 +231,23 @@ module Parse
       end
 
       # Fields defined locally but missing on server.
-      # @return [Hash] field name => type pairs
+      #
+      # Iterates the model's `field_map` (one entry per canonical property,
+      # canonical name => wire column name) rather than `fields` (which carries
+      # both the snake_case and camelCase keys for every property and therefore
+      # double-counts multi-word fields). The wire name resolved from
+      # `field_map` is the authoritative server column — including custom
+      # `field:` mappings — so this both dedupes and fixes custom-column
+      # detection. Result is keyed by the CANONICAL (snake) name with the type
+      # taken from `fields[name]`.
+      # @return [Hash] canonical field name => type pairs
       def missing_on_server
-        return local_fields unless server_exists?
-
-        local = local_fields
-        server = server_field_names
+        server = server_exists? ? server_field_names : []
         missing = {}
-        local.each do |name, type|
-          name_str = name.to_s.camelize(:lower)
-          missing[name] = type unless server.include?(name_str) || core_field?(name)
+        @model_class.field_map.each do |name, wire|
+          next if core_field?(name)
+          next if server.include?(wire.to_s)
+          missing[name] = @model_class.fields[name]
         end
         missing
       end
@@ -262,15 +269,25 @@ module Parse
       end
 
       # Fields with type mismatches.
-      # @return [Hash] field name => { local: type, server: type }
+      #
+      # Iterates `field_map` (canonical name => wire column) rather than
+      # deriving the server key with `camelize(:lower)`, so a property with a
+      # custom `field:` wire column (e.g. `property :post_id, field:
+      # "postIdentifier"`) resolves to its real server column instead of a
+      # camelized guess. This both dedupes multi-word fields (which appear
+      # under two keys in `fields`) and matches the `missing_on_server`
+      # resolution path, so type drift on custom-mapped columns is no longer
+      # silently skipped.
+      # @return [Hash] canonical field name => { local: type, server: type }
       def type_mismatches
         return {} unless server_exists?
 
         mismatches = {}
-        local_fields.each do |name, local_type|
+        @model_class.field_map.each do |name, wire|
           next if core_field?(name)
-          name_str = name.to_s.camelize(:lower)
-          server_type = @server_schema.field_type(name_str)
+          local_type = @model_class.fields[name]
+          next if local_type.nil?
+          server_type = @server_schema.field_type(wire.to_s)
           next unless server_type
 
           # Normalize types for comparison
@@ -285,11 +302,30 @@ module Parse
       end
 
       # Check if schemas are in sync.
+      #
+      # Strict / bidirectional: requires the local and server schemas to match
+      # in BOTH directions — no fields missing on the server, no fields missing
+      # locally, and no type mismatches. A server that is a strict superset of
+      # the local model is NOT "in sync" by this measure (use
+      # {#server_covers_local?} for the one-way local ⊆ server check).
       # @return [Boolean]
       def in_sync?
         missing_on_server.empty? && missing_locally.empty? && type_mismatches.empty?
       end
 
+      # Check whether the server schema covers every locally-defined field.
+      #
+      # One-way (local ⊆ server): true when nothing the model declares is
+      # missing on the server and there are no type mismatches. Unlike
+      # {#in_sync?}, this ignores server-only columns, so a server that is a
+      # strict superset of the local model still satisfies it. This is the
+      # predicate that determines whether a migration has any work to do —
+      # extra server columns are not something the migrator would add.
+      # @return [Boolean]
+      def server_covers_local?
+        missing_on_server.empty? && type_mismatches.empty?
+      end
+
       # Generate a human-readable summary.
       # @return [String]
       def summary
@@ -355,9 +391,17 @@ module Parse
       end
 
       # Check if migration is needed.
+      #
+      # A migration is needed when the class does not yet exist on the server,
+      # or when the server does not already cover every locally-defined field.
+      # Defined in terms of the one-way {SchemaDiff#server_covers_local?} rather
+      # than the strict bidirectional {SchemaDiff#in_sync?} so that a server
+      # which is a strict superset of the local model (extra server-only
+      # columns the migrator would never add) does not report a "needed"
+      # migration with zero operations.
       # @return [Boolean]
       def needed?
-        !@diff.in_sync? || !@diff.server_exists?
+        !@diff.server_exists? || !@diff.server_covers_local?
       end
 
       # Get the operations that would be performed.
@@ -372,7 +416,7 @@ module Parse
         @diff.missing_on_server.each do |name, type|
           ops << {
             action: :add_field,
-            field: name.to_s.camelize(:lower),
+            field: @model_class.field_map[name].to_s,
             type: REVERSE_TYPE_MAP[type] || "String",
           }
         end
@@ -424,7 +468,7 @@ module Parse
 
         # Add missing fields
         @diff.missing_on_server.each do |name, type|
-          field_name = name.to_s.camelize(:lower)
+          field_name = @model_class.field_map[name].to_s
           field_schema = { "fields" => { field_name => field_definition(type) } }
 
           response = @client.update_schema(@model_class.parse_class, field_schema)
@@ -444,15 +488,20 @@ module Parse
 
       def build_schema
         fields = {}
-        @model_class.fields.each do |name, type|
+        # Iterate `field_map` (canonical name => wire column) rather than
+        # `fields`, which carries both the snake_case and camelCase keys for
+        # every property and would emit a duplicate/phantom column for each
+        # multi-word or custom-`field:` property.
+        @model_class.field_map.each do |name, wire|
           next if %i[id object_id created_at updated_at acl objectId createdAt updatedAt ACL].include?(name)
-          field_name = name.to_s.camelize(:lower)
-          fields[field_name] = field_definition(type)
+          fields[wire.to_s] = field_definition(@model_class.fields[name])
         end
 
-        # Add pointer targets
+        # Add pointer targets. `references` is keyed by the wire column name
+        # (the `parse_field`), so use it as-is — do not re-camelize, which
+        # would corrupt custom `field:` pointer columns.
         @model_class.references.each do |name, target_class|
-          field_name = name.to_s.camelize(:lower)
+          field_name = name.to_s
           fields[field_name] = {
             "type" => "Pointer",
             "targetClass" => target_class.to_s,

data/lib/parse/stack/version.rb

@@ -2,10 +2,10 @@
 # frozen_string_literal: true
 
 module Parse
-  # @author Anthony Persaud, Henry Spindell, Adrian Curtin
+  # @author Adrian Curtin, Anthony Persaud, Henry Spindell
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "5.1.1"
+    VERSION = "5.2.0"
   end
 end

data/parse-stack-next.gemspec

@@ -6,7 +6,7 @@ require "parse/stack/version"
 Gem::Specification.new do |spec|
   spec.name = "parse-stack-next"
   spec.version = Parse::Stack::VERSION
-  spec.authors = ["Anthony Persaud", "Henry Spindell", "Adrian Curtin"]
+  spec.authors =  ["Adrian Curtin", "Anthony Persaud", "Henry Spindell"]
   spec.email = ["adrian+parse-stack@neurosynq.net"]
 
   spec.summary = %q{Parse Server SDK for Ruby — ORM, queries, auth, and MongoDB-direct access}

data/scripts/docker/docker-compose.atlas.yml

@@ -8,7 +8,7 @@
 #   Reset:  docker-compose -f scripts/docker/docker-compose.atlas.yml down -v && docker-compose -f scripts/docker/docker-compose.atlas.yml up -d
 #
 # Run tests:
-#   ATLAS_URI="mongodb://localhost:27020/parse_atlas_test?directConnection=true" ruby -Ilib:test test/lib/parse/atlas_search_integration_test.rb
+#   ATLAS_URI="mongodb://localhost:29020/parse_atlas_test?directConnection=true" ruby -Ilib:test test/lib/parse/atlas_search_integration_test.rb
 #
 # Stability notes (see commit history for context):
 #   The mongodb-atlas-local image runs a supervisor ("runner") that intentionally
@@ -19,13 +19,17 @@
 #   which checks both mongod AND mongot. We rely on that built-in healthcheck
 #   rather than overriding it with a faster mongosh probe.
 
+# Distinct Compose project name — kept separate from the main test stack
+# (psnext-it) so `down` on one never tears down the other.
+name: ${PSNEXT_PREFIX:-psnext-it}-atlas
+
 services:
   atlas-local:
     # Pinned patch tag rather than the floating :8.0 — mongodb-atlas-local has
     # known per-patch start-up flakiness (see testcontainers/testcontainers-java#10267
     # and MongoDB community forum 321179). Bump deliberately, not by drift.
     image: mongodb/mongodb-atlas-local:8.0.10
-    container_name: parse-stack-atlas-local
+    container_name: ${PSNEXT_PREFIX:-psnext-it}-atlas
     # `hostname` is called out by the official compose example — the embedded
     # single-node replica set advertises this name, and a stable value makes
     # restart-after-down work cleanly.
@@ -37,15 +41,15 @@ services:
       MONGOT_LOG_FILE: /dev/stderr
     # Loopback-only by default — Atlas Local has no auth configured.
     ports:
-      - "${ATLAS_BIND:-127.0.0.1}:27020:27017"
+      - "${ATLAS_BIND:-127.0.0.1}:${ATLAS_HOST_PORT:-29020}:27017"
     volumes:
       # Persist mongod data, replset config, and — critically — the mongot
       # Lucene index directory. Without /data/mongot persistence, every restart
       # forces a full search re-index, which lengthens "ready" time and is a
       # real source of test flakiness. Matches the official compose example.
-      - atlas-data:/data/db
-      - atlas-configdb:/data/configdb
-      - atlas-mongot:/data/mongot
+      - psnext-it-atlas-data:/data/db
+      - psnext-it-atlas-configdb:/data/configdb
+      - psnext-it-atlas-mongot:/data/mongot
     # Recover from genuine crashes automatically. Test runs `docker compose down`
     # explicitly, so this does not interfere with teardown.
     restart: unless-stopped
@@ -59,7 +63,7 @@ services:
 
   atlas-init:
     image: mongodb/mongodb-atlas-local:8.0.10
-    container_name: parse-stack-atlas-init
+    container_name: ${PSNEXT_PREFIX:-psnext-it}-atlas-init
     depends_on:
       atlas-local:
         # Uses the image's built-in healthcheck (see above), so this now waits
@@ -71,6 +75,6 @@ services:
     restart: "no"
 
 volumes:
-  atlas-data:
-  atlas-configdb:
-  atlas-mongot:
+  psnext-it-atlas-data:
+  psnext-it-atlas-configdb:
+  psnext-it-atlas-mongot:

data/scripts/docker/docker-compose.test.yml

@@ -1,31 +1,35 @@
 version: '3.8'
 
+# Distinct Compose project name so this stack never shares containers,
+# networks, or volumes with another Parse test system on the same host.
+name: ${PSNEXT_PREFIX:-psnext-it}
+
 services:
   mongo:
     image: mongo:8
-    container_name: parse-stack-test-mongo
+    container_name: ${PSNEXT_PREFIX:-psnext-it}-mongo
     # Bind to loopback so the test database isn't reachable from the LAN
     # when a developer runs `docker-compose up`. Override with
     # `MONGO_BIND=0.0.0.0` if you really want it exposed.
     ports:
-      - "${MONGO_BIND:-127.0.0.1}:27019:27017"
+      - "${MONGO_BIND:-127.0.0.1}:${MONGO_HOST_PORT:-29017}:27017"
     environment:
       MONGO_INITDB_ROOT_USERNAME: ${MONGO_ROOT_USER:-admin}
       MONGO_INITDB_ROOT_PASSWORD: ${MONGO_ROOT_PASSWORD:-password}
       MONGO_INITDB_DATABASE: admin
     volumes:
-      - mongo-data:/data/db
+      - psnext-it-mongo-data:/data/db
       - ./mongo-init.js:/docker-entrypoint-initdb.d/mongo-init.js:ro
 
   parse:
     build:
       context: ..
       dockerfile: docker/Dockerfile.parse
-    container_name: parse-stack-test-server
+    container_name: ${PSNEXT_PREFIX:-psnext-it}-server
     # Bind to loopback by default — Parse Server with the test master key
     # has no business being reachable on a developer's LAN.
     ports:
-      - "${PARSE_BIND:-127.0.0.1}:2337:1337"
+      - "${PARSE_BIND:-127.0.0.1}:${PARSE_HOST_PORT:-29337}:1337"
     # `host.docker.internal` is needed so Parse Server can POST to the
     # in-process WEBrick that backs webhook integration tests. Docker
     # Desktop on Mac/Windows resolves this natively; on Linux we map it
@@ -45,10 +49,10 @@ services:
       # `start-parse.sh` will abort if any of these is unset, so any
       # name drift here surfaces immediately rather than booting Parse
       # Server with whatever placeholder default the SDK README documents.
-      PARSE_SERVER_APPLICATION_ID: ${PARSE_APP_ID:-myAppId}
-      PARSE_SERVER_MASTER_KEY:     ${PARSE_MASTER_KEY:-myMasterKey}
-      PARSE_SERVER_REST_API_KEY:   ${PARSE_API_KEY:-test-rest-key}
-      PARSE_SERVER_DATABASE_URI:   mongodb://${MONGO_ROOT_USER:-admin}:${MONGO_ROOT_PASSWORD:-password}@mongo:27017/parse?authSource=admin
+      PARSE_SERVER_APPLICATION_ID: ${PARSE_APP_ID:-psnextItAppId}
+      PARSE_SERVER_MASTER_KEY:     ${PARSE_MASTER_KEY:-psnextItMasterKey}
+      PARSE_SERVER_REST_API_KEY:   ${PARSE_API_KEY:-psnext-it-rest-key}
+      PARSE_SERVER_DATABASE_URI:   mongodb://${MONGO_ROOT_USER:-admin}:${MONGO_ROOT_PASSWORD:-password}@mongo:27017/parse_stack_next_it?authSource=admin
       # Accept client-supplied objectId on create. Required by the
       # `parse_reference precompute: true` DSL. The SDK only forwards
       # client objectIds under master-key authority; for non-master
@@ -78,36 +82,36 @@ services:
 
   redis:
     image: redis:7-alpine
-    container_name: parse-stack-test-redis
+    container_name: ${PSNEXT_PREFIX:-psnext-it}-redis
     # Loopback-only by default. Used by the cache integration test
     # (cache_redis_integration_test.rb) and the synchronize-create lock
     # tests. Override with `REDIS_BIND=0.0.0.0` if you need to point a
     # remote client at it during debugging.
     ports:
-      - "${REDIS_BIND:-127.0.0.1}:6399:6379"
+      - "${REDIS_BIND:-127.0.0.1}:${REDIS_HOST_PORT:-29379}:6379"
     command: ["redis-server", "--save", "", "--appendonly", "no"]
 
   parse-dashboard:
     image: parseplatform/parse-dashboard:9
-    container_name: parse-stack-test-dashboard
+    container_name: ${PSNEXT_PREFIX:-psnext-it}-dashboard
     # Loopback-only by default. This compose is for `rake test:integration`
     # and local debugging; do not expose to the network.
     ports:
-      - "${DASHBOARD_BIND:-127.0.0.1}:4040:4040"
+      - "${DASHBOARD_BIND:-127.0.0.1}:${DASHBOARD_HOST_PORT:-29040}:4040"
     environment:
       # `allowInsecureHTTP` and `useEncryptedPasswords: false` are kept
       # because this stack runs over plain HTTP on loopback. Do NOT copy
       # these settings to a deployed environment.
       PARSE_DASHBOARD_ALLOW_INSECURE_HTTP: "1"
-      PARSE_SERVER_MASTER_KEY: ${PARSE_MASTER_KEY:-myMasterKey}
-      PARSE_SERVER_APPLICATION_ID: ${PARSE_APP_ID:-myAppId}
-      PARSE_SERVER_URL: http://localhost:2337/parse
+      PARSE_SERVER_MASTER_KEY: ${PARSE_MASTER_KEY:-psnextItMasterKey}
+      PARSE_SERVER_APPLICATION_ID: ${PARSE_APP_ID:-psnextItAppId}
+      PARSE_SERVER_URL: http://localhost:${PARSE_HOST_PORT:-29337}/parse
       PARSE_DASHBOARD_CONFIG: |
         {
           "apps": [{
-            "serverURL": "http://localhost:2337/parse",
-            "appId": "${PARSE_APP_ID:-myAppId}",
-            "masterKey": "${PARSE_MASTER_KEY:-myMasterKey}",
+            "serverURL": "http://localhost:${PARSE_HOST_PORT:-29337}/parse",
+            "appId": "${PARSE_APP_ID:-psnextItAppId}",
+            "masterKey": "${PARSE_MASTER_KEY:-psnextItMasterKey}",
             "appName": "ParseStackTest"
           }],
           "users": [{
@@ -121,4 +125,4 @@ services:
       - parse
 
 volumes:
-  mongo-data:
+  psnext-it-mongo-data:

data/scripts/docker/mongo-init.js

@@ -1,6 +1,6 @@
 // MongoDB initialization script
 // This script runs when the MongoDB container is first created
-// It grants the admin user access to the parse database for direct queries
+// It grants the admin user access to the parse_stack_next_it database for direct queries
 
 // The admin user needs readWriteAnyDatabase role to access all databases
 db = db.getSiblingDB('admin');
@@ -11,8 +11,8 @@ db.grantRolesToUser('admin', [
   { role: 'dbAdminAnyDatabase', db: 'admin' }
 ]);
 
-// Initialize the parse database
-db = db.getSiblingDB('parse');
+// Initialize the parse_stack_next_it database
+db = db.getSiblingDB('parse_stack_next_it');
 
 // Create a placeholder collection to ensure the database exists
 db.createCollection('_init');