parse-stack-next 5.5.4 → 5.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97d41b5209b0365349812d166993421d4f25ae734dff25141c141decf0c54cc4
-  data.tar.gz: c0e3b483da29241890500469939f79a44396966e321827283dc3be327d7bdc6c
+  metadata.gz: ef7d7de047cc0a3b4a21f3b080745f36f67cd2a53a81787fe53fdbb68fc3ec41
+  data.tar.gz: 74af45b9e2f334ca13c99419fe71d1653b9a218dffcf2a02ff801088ab86850b
 SHA512:
-  metadata.gz: e01b065bc9e57307d95dcba6ae474a025130d694f5cf30560441af37d31f047a79fd1c65dc3e8543024a1d449a31b30bf82d7a3ba4908a512b61975de4558353
-  data.tar.gz: d5b0a9ac73f321dc78953924d175549bf6d5ee96918907851b2dc1589dd3131941d2c1f5eb30a166b9b806abea70d416ae7f869eb9dfcf781b3f10f1879f629b
+  metadata.gz: e31f81f269bf874438617b00a01f1fb095fc7853f544d0a38f02aff8f58e21b14e8561650e3d3fb29bad6ff6276722992451a4f78b640481de3e5ab421cd033a
+  data.tar.gz: 71063ac383cb393af56969a1b631885585f5863b764218d7bee65b79a34cc9b469a885e96cf5bac5239ec66c140602e2bbe8197a46fa90ff4568cb240571e80f

data/CHANGELOG.md

@@ -4,8 +4,10 @@
 
 #### Dependency updates
 
-- **CHANGED**: Bumped `graphql` to 2.6.5 (from 2.6.3) in the locked
-  dependencies.
+- **CHANGED**: Bumped locked dependencies to their latest compatible
+  releases — `graphql` 2.6.3 → 2.6.5, `i18n` 1.15.1 → 1.15.2, `json` 2.19.9
+  → 2.21.1, `pp` 0.6.3 → 0.6.4, `rdoc` 7.2.0 → 8.0.0, `tilt` 2.7.0 → 2.8.0,
+  and `yard` 0.9.44 → 0.9.45.
 
 ### 5.5.3
 
@@ -4506,17 +4508,17 @@ query.where(genre: "rock").last_updated(limit: 3)
 
 ```ruby
 # Default behavior - pointers for storage (backward compatible)
-post.assets.as_json
+post.documents.as_json
 # => [{"__type"=>"Pointer", "className"=>"Document", "objectId"=>"abc"}, ...]
 
 # Serialize with fetched fields (no autofetch, pointers stay as pointers)
-post.assets.as_json(pointers_only: false)
+post.documents.as_json(pointers_only: false)
 # => [{"objectId"=>"abc", "file"=>{...}, "caption"=>"My photo", ...}, ...]
 
-# In webhooks, manually override assets serialization:
+# In webhooks, manually override documents serialization:
 cloud_results.map do |post|
   json = post.as_json
-  json['assets'] = post.assets.as_json(pointers_only: false) if post.assets.any?
+  json['documents'] = post.documents.as_json(pointers_only: false) if post.documents.any?
   json
 end
 ```

data/README.md

@@ -4,14 +4,14 @@
 
 A full-featured Ruby client SDK for [Parse Server](http://parseplatform.org/). [parse-stack-next](https://github.com/neurosynq/parse-stack-next) is a Ruby client SDK, REST client, and Active Model ORM for [Parse Server](http://parseplatform.org/), combining a low-level API client, a query engine, an object-relational mapper (ORM), and a Cloud Code Webhooks rack application in a single gem.
 
-### What's new in 5.5
+## What's new in 5.5
 
 - **5.5.0 — Multimodal bytes-fetch with magic-byte MIME verification** — `embed_image ..., source: :bytes` has the SDK download an image itself through the `Parse::File.safe_open_url` SSRF primitive, verify the content by **magic-byte sniff** (the `Content-Type` header is never consulted — a `.jpg` URL serving HTML is refused), cross-check the URL extension, enforce a `Parse::Embeddings.allowed_image_types` allowlist, strip EXIF/XMP metadata **by default** (JPEG APP1, PNG `eXIf`, WebP `EXIF`/`XMP ` chunks; opt out with `exif_strip: false`), and forward the verified bytes to Voyage/Cohere as a base64 data URI. No provider-side URL fetch occurs, so the `trust_provider_url_fetch` sentinel is not required — the host allowlist still applies. See [CHANGELOG.md](./CHANGELOG.md)
 - **5.5.0 — Embedding-model migration tooling** — `Class.reembed!(only_stale: true)` bulk re-embeds rows through the current provider/model (resumable; skips rows already current), driven by the new auto-declared `<into>_meta` provenance sibling (`{provider, model, dimensions, modality, embedded_at}`, stamped on every recompute). `Parse::Embeddings::BatchEmbedder` adds batch-level requests-per-minute pacing and exponential backoff for bulk jobs; `Parse::Embeddings::Cache.enable!` adds an opt-in query-embed cache keyed by `(provider, model, input_type, input-hash)` so repeated identical queries skip the provider round-trip. See [CHANGELOG.md](./CHANGELOG.md)
 - **5.5.0 — Vector index drift detection** — on first auto-discovered use of an Atlas vectorSearch index, the SDK verifies the deployed index's `numDimensions`/`similarity` against the `:vector` property declaration and confirms a registered `agent_tenant_scope` field is covered as a `type: "filter"` path. Policy via `Parse::VectorSearch.index_drift_policy` (`:warn` default / `:raise` / `:ignore`). `Parse::Schema::SearchIndexMigrator` now auto-includes the tenant-scope field in `vectorSearch` declarations, so newly created indexes support tenant-scoped pre-filtering out of the box. See [CHANGELOG.md](./CHANGELOG.md)
 - **5.5.0 — Retrieval spend-cap and filter hardening** — the per-tenant embedding spend cap now covers every query-embed path (`find_similar(text:)`, `hybrid_search(text:)`, `Parse::Retrieval.retrieve`), not just the `semantic_search` agent tool; tenant identity resolves through the ambient `Parse.with_cache_tenant` scope. Caller-supplied retrieval filters now translate Parse pointer values to storage form (`{ owner: user }` → `{ "_p_owner" => "_User$id" }`), so pointer filters match rows instead of silently matching nothing. See [CHANGELOG.md](./CHANGELOG.md)
 
-### What's new in 5.4
+## What's new in 5.4
 
 - **5.4.0 — Hybrid search + reranking for RAG** — `Class.hybrid_search(text:, lexical:, vector:, k:, fusion:)` fuses a lexical Atlas Search branch with a `$vectorSearch` branch using reciprocal-rank fusion (RRF): lexical search nails exact tokens (codes, proper nouns), vector search nails paraphrase, and fusing the two beats either alone. Each branch enforces ACL/CLP independently before fusion (no separate hydration fetch to secure); results carry `#hybrid_score` / `#hybrid_ranks`. `Parse::VectorSearch::Hybrid.rank_fusion_supported?` detects Atlas 8.0+ native `$rankFusion` by a cached behavioural probe (native execution is opt-in; client-side RRF is the always-enforced default). `Parse::Retrieval::Reranker` adds cross-encoder reranking (`Reranker::Cohere` over `/v2/rerank`, plus a deterministic `Reranker::Fixture`), wired into `Parse::Retrieval.retrieve(hybrid:, rerank:)`. `Parse::Embeddings::SpendCap` adds an opt-in per-tenant embedding token cap (hard-refuse) at the `semantic_search` agent-tool boundary. See [CHANGELOG.md](./CHANGELOG.md) and [`docs/atlas_vector_search_guide.md`](./docs/atlas_vector_search_guide.md)
 - **5.4.0 — Vector backfill, visibility, and webhook redaction** — `Class.embed_pending!` backfills embeddings for records whose managed `:vector` field is null (objectId-cursor pagination); `Parse::Object#compute_embedding!` forces an in-place recompute without a save; `vector_visibility :owner_only | :public` controls whether a class's vectors appear in `as_json` by default; and webhook trigger payloads now strip declared `:vector` columns by default (a `:public` class keeps them). See [CHANGELOG.md](./CHANGELOG.md)
@@ -20,13 +20,13 @@ A full-featured Ruby client SDK for [Parse Server](http://parseplatform.org/). [
 - **5.4.0 — Audience hash queries persist correctly** — `Parse::Audience#query` is now stored as a JSON string on the wire to match Parse Server's `_Audience.query` column type, so saving an audience with a `Hash` query no longer fails the server schema check. The public API is unchanged — assign a `Hash`, read a `Hash` back. See [CHANGELOG.md](./CHANGELOG.md)
 - **5.4.0 — Faster AtlasSearch role-cache expiry** — `Parse::AtlasSearch` `role_cache_ttl` now defaults to 30 seconds (was 120) so a role grant or revoke is reflected in `$search` ACL decisions sooner, at the cost of slightly more frequent role lookups. See [CHANGELOG.md](./CHANGELOG.md)
 
-### What's new in 5.3
+## What's new in 5.3
 
 - **5.3.0 — Run webhook handlers (and clients) as the calling user** — Parse Server embeds the caller's live session token in every trigger webhook fired by a logged-in user. A handler can now opt in to acting on the server *as that user* — full ACL/CLP/`protectedFields` enforcement, no master key. `payload.session_token` exposes the captured token (`nil` for master-key requests; still scrubbed from `payload.user`/`payload.object`/`as_json`/logs); `payload.user_agent` returns a client-mode `Parse::Agent`, and `payload.user_client` a non-master `Parse::Client` with the token **bound** so even raw REST calls authorize as the user. The same user-scoped client is available client-side via `Parse::User#session_client` and the `Parse::Client#become(token)` primitive, with `Parse::Client#with_session { … }` for block scoping. Backed by a new `Parse::Client.new(session_token:)` option. See [Acting as the calling user](#acting-as-the-calling-user)
 - **5.3.0 — Pluralized class-name aliases** — referencing the plural form of a model constant now resolves to that class, so `Posts.where(:author.eq => user).count` works for a class `Post`. The alias is created lazily on first reference and is the *same class object*, so every class method (`query`/`where`, `count`, `find`, `all`, scopes) works through it and `Posts.parse_class` still returns `"Post"`. Because it is the same class it adds no `Parse::Object.descendants` entry and never registers a separate Parse schema class. Classes whose name already ends in `s` are skipped by the automatic path; non-Parse plurals and typos fall through to a normal `NameError`. On by default — opt out with `Parse.pluralized_aliases = false` (or `PARSE_PLURALIZED_ALIASES=false`). For a custom plural, an `s`-ending class, or a namespaced model, call `pluralized_alias!` in the class body. See [Pluralized class-name aliases](#pluralized-class-name-aliases)
 - **5.3.0 — afterSave create reports changed fields; force_ssl-consistent file equality** — a trigger handler that keys off dirty tracking now sees every field on an `afterSave` *create*, symmetric with `afterSave` updates: the built object marks each populated data property changed (from `nil`) while `createdAt`/`updatedAt`/`ACL`/`objectId` stay clean and object readability, `new?`, and `existed?` are unchanged — so a handler that builds a payload from `*_changed?` / `changes` works uniformly across create and update. Separately, `Parse::File#==` now compares both files through the canonical `url` reader, so two files at the same location compare equal regardless of `Parse::File.force_ssl` (and `a == b` matches `b == a`), and a re-signed URL for the same object no longer reads as a change. See [Cloud Code Triggers](#cloud-code-triggers)
 
-### What's new in 5.2
+## What's new in 5.2
 
 - **5.2.1 — Webhook triggers receive the full Parse object** — trigger handlers (`beforeSave`/`afterSave`/…) now get the complete server object (`createdAt`/`updatedAt`, `ACL`, internal fields); only live credentials (session tokens, password hashes) are stripped. `Parse::Object#existed?` / `#new?` are reliable in `afterSave`, `afterSave` updates carry dirty tracking, and the model lifecycle runs in ActiveModel order — `before_save → before_create` then `after_create → after_save` — so `before_create` now fires for REST/JS/Auth0 creates (and `after_save` no longer double-fires). See [Cloud Code Triggers](#cloud-code-triggers)
 - **Retrieval layer — `Parse::Retrieval` (`Parse::RAG`)** — `Parse::Retrieval.retrieve(query:, klass:, k:, filter:, tenant_scope:, …)` embeds a natural-language query, runs Atlas `$vectorSearch` through the existing ACL-enforcing `find_similar`, and splits each retrieved document's text field into scored `Parse::Retrieval::Chunk`s. Chunking is presentation-only (embedding stays one-vector-per-record), via `Parse::Retrieval::Chunker::FixedSizeOverlap(size:, overlap:, by:, max_chunks_per_document:)` (subclass `Chunker::Base` for custom strategies). ACL is mongo-direct (no REST two-stage); tenant scope folds into the Atlas pre-filter
@@ -40,7 +40,7 @@ A full-featured Ruby client SDK for [Parse Server](http://parseplatform.org/). [
 
 See [CHANGELOG.md](./CHANGELOG.md) for the full 5.2 entry.
 
-### What's new in 5.1
+## What's new in 5.1
 
 - **`Parse::File` URL normalization + presigned-URL stash** — `Parse::File#url=` and `attributes=` now strip signed-URL query parameters (`X-Amz-Signature`, `AWSAccessKeyId`, `Key-Pair-Id`, etc.) before storage; the bare canonical URL lands in `@url`, and the original signed URL is stashed in `file.presigned_url` with a data-driven expiry in `file.presigned_url_expires_at`. New `file.presigned_url_valid?(buffer: 60)` predicate, configurable `Parse::File.signed_url_policy = :strip | :raise`, and `Parse::File.log_filter` / `log_filter_strict` regexes for `lograge` / Sentry / Honeybadger scrubbers. `Parse::File#inspect` no longer emits the URL — see CHANGELOG for the error-reporter payload migration callout
 - **`Parse::Lock` — public TTL-bounded mutual-exclusion primitive** — `Parse::Lock.acquire(key, ttl:, wait:) { … }` exposes the Redis-backed lock previously hidden inside `first_or_create!` as a first-class API. In-process `Mutex` fallback for memory-backed caches, fails closed on backend errors, HMAC-keyed via `PARSE_STACK_LOCK_SECRET`, namespace-separated from `first_or_create!` so the two cannot collide
@@ -56,7 +56,7 @@ See [CHANGELOG.md](./CHANGELOG.md) for the full 5.2 entry.
 
 See [CHANGELOG.md](./CHANGELOG.md) for the full 5.1 entry, including breaking changes, migration callouts, and the round-by-round security review notes.
 
-### What's new in 5.0
+## What's new in 5.0
 
 - **RAG foundation** — `:vector` property type, `Parse::Embeddings` provider registry shipping built-in adapters for OpenAI, Cohere (v3 + v4.0 Matryoshka text-mode), Voyage (incl. open-weight `voyage-4-nano` and `voyage-multimodal-3` text-mode), Jina v3/v4/v5/code, Qwen 3 (DashScope), and a generic `LocalHTTP` client for Ollama / LM Studio / vLLM / TEI. `Klass.find_similar(vector:/text:, k:)` over Atlas `$vectorSearch`, and an `embed` class macro that digest-tracks source fields so vectors only recompute when content changes
 - **`Parse::Cache::Redis`** — Moneta-compatible Redis cache wrapper with a built-in `ConnectionPool`, optional `cache_namespace:` for multi-tenant Redis sharing, and graceful degrade on pool saturation
@@ -64,12 +64,12 @@ See [CHANGELOG.md](./CHANGELOG.md) for the full 5.1 entry, including breaking ch
 - **MCP transport hardening** — Streamable HTTP `Mcp-Session-Id` header (renamed from `X-MCP-Session-Id`, **breaking**), `MCP-Protocol-Version` validation, `DELETE /` session termination, structured-content (`outputSchema`) on built-in tools, optional `health_path:` liveness probe
 - **`Parse::GraphQL::TypeGenerator`** — generate `graphql-ruby` types directly from your `Parse::Object` subclasses (no Parse Server round-trip), with `:vector` columns surfaced as `[Float]` and association registries (`has_one_associations`, `has_many_associations`) populated at DSL time
 - **LiveQuery promoted to stable** — the experimental warning is removed; `Parse.live_query_enabled = true` is retained as a network-egress safety toggle, not a stability gate
-- **Server-version deprecation warning** — one-shot warning when connecting to Parse Server below the supported floor (currently 7.0.0); silence with `Parse.suppress_server_version_warning = true`
+- **Server-version deprecation warning** — one-shot warning when connecting to a Parse Server older than the configured threshold (default `7.0.0`, override with `PARSE_DEPRECATED_SERVER_VERSION_BELOW`); silence with `Parse.suppress_server_version_warning = true`. The **supported baseline is Parse Server 9.x** (the SDK is developed and tested against a pinned `parse-server:9.9.0`); the default warning threshold is intentionally conservative so older deployments only get an advisory, not a hard break.
 - **`mongo_relation_index :field, dedup: true`** — register a compound `{owningId, relatedId}` UNIQUE on relation join collections to prevent duplicate-pair subscriptions without breaking `has_many` semantics
 
 See [CHANGELOG.md](./CHANGELOG.md) for the full 5.0 entry, including security-hardening notes and Ruby 3.x cleanup.
 
-### Core capabilities
+## Core capabilities
 
 > **Vector search requires MongoDB Atlas (or Atlas Local).** The `:vector`
 > property, `find_similar`, `hybrid_search`, and `Parse::Retrieval` all
@@ -104,16 +104,16 @@ Below is a [quick start guide](#overview). See also the [Usage Guide](./docs/usa
 
 > **Note:** API reference docs are published at [neurosynq.github.io/parse-stack-next](https://neurosynq.github.io/parse-stack-next/index.html). Generated via YARD from the current source; covers the full 5.x surface.
 
-### Credits
+## Credits
 
 This project (`parse-stack-next`) is a continuation of the [Parse Stack framework](https://github.com/modernistik/parse-stack) originally created by [Modernistik](https://www.modernistik.com). We are grateful for their foundational work and continue to build upon it under the [neurosynq](https://github.com/neurosynq) organization.
 
-### Code Status
+## Code Status
 [![Gem Version](https://img.shields.io/gem/v/parse-stack-next.svg)](https://rubygems.org/gems/parse-stack-next)
 [![Downloads](https://img.shields.io/gem/dt/parse-stack-next.svg)](https://rubygems.org/gems/parse-stack-next)
 [![Releases](https://img.shields.io/github/v/release/neurosynq/parse-stack-next)](https://github.com/neurosynq/parse-stack-next/releases)
 
-#### Tutorial Videos
+### Tutorial Videos
 
 The following videos were recorded for the original parse-stack gem. The model, query, and association surface they cover is unchanged in parse-stack-next, so they remain a useful introduction; see the [Usage Guide](./docs/usage_guide.md) for v5.x-specific features (vector search, Redis cache, agent tools).
 
@@ -177,7 +177,7 @@ Parse.auto_generate_models!
 # or define custom Subclasses (Highly Recommended)
 class Song < Parse::Object
   property :name
-  property :play, :integer
+  property :plays, :integer
   property :audio_file, :file
   property :tags, :array
   property :released, :date
@@ -248,7 +248,7 @@ Runnable, self-contained scripts live in [`examples/`](examples/) — see
 
 ## Release History
 
-**Current version: 5.4.0** | **Ruby 3.2+ required**
+**Current version: 5.5.5** | **Ruby 3.2+ required**
 
 The 5.0 highlights (vector search / RAG, pooled Redis cache, AS::N instrumentation, MCP transport hardening, GraphQL type generation) are summarized in the [What's new in 5.0](#whats-new-in-50) section above. Earlier releases are recorded below.
 
@@ -294,6 +294,19 @@ Per-version detail lives in [CHANGELOG.md](./CHANGELOG.md) and on the [Releases
 
 The 1.x line is the original [`modernistik/parse-stack`](https://github.com/modernistik/parse-stack) — Active Model ORM, REST client, query DSL, associations, and Cloud Code webhooks for Parse Server. `parse-stack-next` is a continuation of that work; the first release published under the new gem name is **4.5.0** (above), on RubyGems as [`parse-stack-next`](https://rubygems.org/gems/parse-stack-next).
 
+## Guides
+
+In-depth guides for the larger subsystems live under [`docs/`](./docs):
+
+- [Usage Guide](./docs/usage_guide.md) — end-to-end tour of models, queries, and CRUD.
+- [Client SDK Guide](./docs/client_sdk_guide.md) — running as an unprivileged (non-master) client: session tokens, `with_session`, row-level ACL enforcement, LiveQuery from the client side.
+- [ACL & CLP Guide](./docs/acl_clp_guide.md) — access-control model, Class-Level Permissions, and how enforcement differs across REST vs mongo-direct.
+- [Direct MongoDB Guide](./docs/mongodb_direct_guide.md) — the `results_direct` / `Parse::MongoDB` path, its authority model, and when to reach for it.
+- [MongoDB Index Optimization Guide](./docs/mongodb_index_optimization_guide.md) — index DSL, schema migrators, and the writer-URI triple-gate.
+- [Atlas & Vector Search Guide](./docs/atlas_vector_search_guide.md) — `$search`, vector search, `find_similar`, `hybrid_search`, embeddings, and RAG retrieval.
+- [AI Agent & MCP Guide](./docs/mcp_guide.md) — `Parse::Agent`, the built-in tools, permission tiers, and the MCP server surface.
+- [Webhooks Guide](./docs/webhooks_guide.md) — Cloud Code webhook receiver, triggers, field guards, and replay protection.
+
 ## Table of Contents
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->

data/bin/parse-console

@@ -76,7 +76,15 @@ opt_parser = OptionParser.new do |o|
   o.on('--url URL', 'Load the env config from a url.') do |url|
     begin
       puts "Loading config: #{url}"
-      json = JSON.load open(url)
+      # SEC-20: do NOT pass a user-supplied string to bare Kernel#open —
+      # `open("|command")` executes a subprocess. Parse an explicit URI and
+      # require an HTTP(S) scheme, then use open-uri's URI::HTTP#open (a real
+      # network fetch), never the Kernel form.
+      uri = URI.parse(url)
+      unless uri.is_a?(URI::HTTP) # URI::HTTPS < URI::HTTP, so this admits both
+        raise "Refusing to load config from a non-HTTP(S) URL: #{url.inspect}"
+      end
+      json = JSON.load(uri.open)
       raise "Contents not a JSON hash." unless json.is_a?(Hash)
       json.each { |k,v| ENV[k.upcase] = v }
       opts[:server_url] ||= ENV['PARSE_SERVER_URL']

data/docs/TEST_SERVER.md

@@ -1,271 +1,148 @@
 # Parse Stack Test Server Setup
 
-This document explains how to set up a local Parse Server for testing the parse-stack Ruby SDK.
+This document explains how to run the local, isolated Parse Server stack used
+to exercise the parse-stack-next Ruby SDK's integration suite.
+
+The stack is namespaced so it never collides with another Parse test system on
+the same machine: a dedicated Compose project, a private `29xxx` host-port
+block, dedicated container/volume names (`psnext-it-*`), loopback-only port
+binds by default, and a dedicated database.
 
 ## Quick Start
 
-### Option 1: Using Make (Recommended)
+### Option 1: Using Make
 
 ```bash
-# Start the test server
-make test-server-start
-
-# Test the connection
-make test-connection
-
-# Run integration tests
-make test-integration
-
-# Stop the test server
-make test-server-stop
+make test-server-start   # bring up the stack
+make test-connection     # verify connectivity
+make test-integration    # run the integration suite
+make test-server-stop    # tear the stack down
 ```
 
-### Option 2: Docker Compose
+### Option 2: Docker Compose directly
 
-1. **Start the test server:**
-   ```bash
-   docker-compose -f docker-compose.test.yml up -d
-   ```
+```bash
+# Start
+docker-compose -f scripts/docker/docker-compose.test.yml up -d
 
-2. **Test the connection:**
-   ```bash
-   ruby test_server_connection.rb
-   ```
+# Verify Parse Server is healthy
+curl http://localhost:29337/parse/health   # => {"status":"ok"}
 
-3. **Run integration tests:**
-   ```bash
-   PARSE_TEST_USE_DOCKER=true bundle exec rake test
-   ```
+# Run integration tests
+PARSE_TEST_USE_DOCKER=true bundle exec rake test:integration
 
-4. **Stop the test server:**
-   ```bash
-   docker-compose -f docker-compose.test.yml down
-   ```
+# Stop
+docker-compose -f scripts/docker/docker-compose.test.yml down
+```
 
-### Option 3: Use Your Own Parse Server
+### Option 3: Use your own Parse Server
 
-Set environment variables to point to your Parse Server:
+Point the suite at any Parse Server by exporting the client-side variables:
 
 ```bash
 export PARSE_TEST_SERVER_URL="http://your-server:1337/parse"
 export PARSE_TEST_APP_ID="your-app-id"
-export PARSE_TEST_API_KEY="your-rest-key"  
+export PARSE_TEST_API_KEY="your-rest-key"
 export PARSE_TEST_MASTER_KEY="your-master-key"
 ```
 
-## Services Included
-
-The Docker Compose setup provides:
-
-- **MongoDB** (port 27017): Database backend
-- **Parse Server** (port 1337): Main API server with custom startup script
-- **Parse Dashboard** (port 4040): Web interface for data management
-
-## Technical Implementation
-
-### Custom Parse Server Image
-
-The setup uses a custom Docker image built on top of `parseplatform/parse-server:8.2.3` that includes:
-
-- **Custom startup script** (`scripts/start-parse.sh`) that sets the `PARSE_SERVER_MASTER_KEY_IPS` environment variable
-- **IP restriction bypass** allowing requests from any IP address (`0.0.0.0/0,::/0`)
-- **Automatic environment variable setup** for proper master key authentication
-
-### Master Key Authentication
-
-The setup resolves Parse Server's IP restriction for master key usage by:
-
-1. Using a custom Docker image with an embedded startup script
-2. Setting `PARSE_SERVER_MASTER_KEY_IPS=0.0.0.0/0,::/0` to allow all IP addresses
-3. This enables schema operations and full master key functionality for testing
-
-### File Structure
-
-```
-parse-stack-next/
-├── scripts/
-│   ├── docker/
-│   │   ├── docker-compose.test.yml # Main Docker Compose configuration
-│   │   └── Dockerfile.parse       # Custom Parse Server image
-│   ├── start-parse.sh             # Startup script with environment setup
-│   └── test_server_connection.rb  # Connection test script
-├── config/
-│   └── parse-config.json    # Parse Server configuration (unused)
-├── test/
-│   ├── cloud/
-│   │   └── main.js         # Cloud Code for testing
-│   └── support/
-│       ├── test_server.rb   # Ruby test helper utilities
-│       └── docker_helper.rb # Docker container management
-└── .env.test              # Environment variable defaults
-```
-
-## Test Configuration
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PARSE_TEST_SERVER_URL` | `http://localhost:1337/parse` | Parse Server URL |
-| `PARSE_TEST_APP_ID` | `myAppId` | Application ID |
-| `PARSE_TEST_API_KEY` | `test-rest-key` | REST API Key |
-| `PARSE_TEST_MASTER_KEY` | `myMasterKey` | Master Key |
-| `PARSE_TEST_USE_DOCKER` | `false` | Auto-manage Docker containers |
-| `PARSE_TEST_AUTO_START` | `false` | Start containers automatically |
-| `PARSE_TEST_AUTO_STOP` | `false` | Stop containers on exit |
-
-### Using `.env.test`
-
-Copy and customize the test environment file:
-
-```bash
-cp .env.test .env.test.local
-# Edit .env.test.local with your settings
-```
-
-## Writing Integration Tests
-
-### Basic Setup
-
-```ruby
-require_relative 'test_helper_integration'
-
-class MyIntegrationTest < Minitest::Test
-  include ParseStackIntegrationTest
-  
-  def test_user_creation
-    with_parse_server do
-      user = create_test_user(username: 'testuser')
-      assert user.id.present?
-      assert_equal 'testuser', user.username
-    end
-  end
-end
-```
-
-### Test Helpers Available
-
-- `with_parse_server { }` - Skip test if server unavailable
-- `create_test_user(attributes)` - Create and track test user
-- `create_test_object(class_name, attributes)` - Create and track test object
-- `reset_database!` - Clear all non-system data
-- `@test_context.track(object)` - Track object for cleanup
-
-### Manual Server Management
-
-```ruby
-# In your tests or console
-require 'test/support/docker_helper'
-
-# Start containers
-Parse::Test::DockerHelper.start!
-
-# Check if running
-Parse::Test::DockerHelper.running?
-
-# View logs
-puts Parse::Test::DockerHelper.logs
-
-# Stop containers
-Parse::Test::DockerHelper.stop!
-```
-
-## Dashboard Access
-
-When using Docker Compose, you can access the Parse Dashboard at:
-- URL: http://localhost:4040
-- Username: `admin`
-- Password: `admin`
-
-## Cloud Code Testing
-
-Sample cloud functions are provided in `test/cloud/main.js`:
-
-```ruby
-# Test cloud functions
-result = Parse::CloudFunction.call('hello', name: 'World')
-assert_equal 'Hello World!', result
-```
+## Services and ports
+
+Every value has a baked-in default, so the stack is isolated even with no env
+file present. Host ports live in the `29xxx` block and bind to `127.0.0.1` by
+default.
+
+| Service         | Host port | Override            | Container             |
+|-----------------|-----------|---------------------|-----------------------|
+| Parse Server    | 29337     | `PARSE_HOST_PORT`   | `psnext-it-server`    |
+| MongoDB         | 29017     | `MONGO_HOST_PORT`   | `psnext-it-mongo`     |
+| Redis           | 29379     | `REDIS_HOST_PORT`   | `psnext-it-redis`     |
+| Parse Dashboard | 29040     | `DASHBOARD_HOST_PORT` | `psnext-it-dashboard` |
+
+- **`PSNEXT_PREFIX`** (default `psnext-it`) names the Compose project and every
+  container. Set it (e.g. `PSNEXT_PREFIX=psnext-ci`) to run a second, fully
+  separate copy.
+- **Versions**: Parse Server is pinned to `parseplatform/parse-server:9.9.0`
+  (see `scripts/docker/Dockerfile.parse`), MongoDB `mongo:8`, Redis
+  `redis:7-alpine`, Dashboard `parseplatform/parse-dashboard:9`.
+- **Database**: Parse uses `parse_stack_next_it`.
+
+## Credentials (compose defaults)
+
+| Setting     | Default             | Compose env             |
+|-------------|---------------------|-------------------------|
+| App ID      | `psnextItAppId`     | `PARSE_APP_ID`          |
+| Master key  | `psnextItMasterKey` | `PARSE_MASTER_KEY`      |
+| REST key    | `psnext-it-rest-key`| `PARSE_API_KEY`         |
+
+These defaults are intentionally non-secret — they only ever bind to loopback.
+Supply real values (and non-loopback binds) via your shell or a secret manager
+if you point the stack at anything shared.
+
+## Security posture (not an anti-pattern)
+
+The stack is hardened by construction, not opened up:
+
+- **Loopback binds by default** — `PARSE_BIND` / `MONGO_BIND` / `REDIS_BIND` /
+  `DASHBOARD_BIND` all default to `127.0.0.1`, so nothing is published on the
+  LAN unless you explicitly override a bind.
+- **Scoped master-key IPs** — Parse Server's `masterKeyIps` is set to loopback
+  plus the private Docker ranges
+  (`127.0.0.1/32,::1/128,172.16.0.0/12,192.168.0.0/16,10.0.0.0/8`) so the
+  Ruby suite and the Dashboard container can use the master key, but it is
+  **not** opened to `0.0.0.0/0`.
+- **Preflight guard** — a `preflight` service (`scripts/docker/preflight.sh`)
+  gates startup and refuses to bring the stack up on a non-loopback bind while
+  still using the default credentials, unless `ALLOW_INSECURE_BIND=1` or real
+  `PARSE_MASTER_KEY` / `MONGO_ROOT_PASSWORD` values are supplied.
+
+## Client-side test variables
+
+The Ruby suite reads these (all have `29xxx` / `psnext-it` defaults):
+
+| Variable                 | Purpose                              |
+|--------------------------|--------------------------------------|
+| `PARSE_TEST_SERVER_URL`  | Parse Server URL (`http://localhost:29337/parse`) |
+| `PARSE_TEST_APP_ID`      | Application ID                       |
+| `PARSE_TEST_API_KEY`     | REST API key                         |
+| `PARSE_TEST_MASTER_KEY`  | Master key                           |
+| `PARSE_TEST_MONGO_URI`   | Mongo URI for mongo-direct tests     |
+| `PARSE_TEST_REDIS_URL`   | Redis URL                            |
+| `PARSE_TEST_LIVE_QUERY_URL` | LiveQuery WebSocket URL           |
+| `PARSE_TEST_USE_DOCKER`  | Auto-manage the Docker stack         |
+
+`.env.test` is a committed reference listing the whole set;
+`set -a; source .env.test; set +a` loads them all at once. Nothing auto-loads
+it — the baked-in defaults apply otherwise.
+
+## Dashboard
+
+With the stack up, the Parse Dashboard is at <http://localhost:29040>.
 
 ## Troubleshooting
 
-### Docker Issues
-
 ```bash
-# Check container status
-docker-compose -f docker-compose.test.yml ps
-
-# View Parse Server logs
-docker logs parse-stack-test-server
-
-# Reset everything
-docker-compose -f docker-compose.test.yml down -v
-docker-compose -f docker-compose.test.yml up -d
-```
-
-### Master Key Authentication Issues
-
-If you see `Request using master key rejected as the request IP address ... is not set in Parse Server option 'masterKeyIps'`:
-
-1. **Verify the custom image is built**: 
-   ```bash
-   docker-compose -f docker-compose.test.yml build parse
-   ```
-
-2. **Check startup script execution**:
-   ```bash
-   docker logs parse-stack-test-server | grep "PARSE_SERVER_MASTER_KEY_IPS"
-   ```
-   Should show: `PARSE_SERVER_MASTER_KEY_IPS: 0.0.0.0/0,::/0`
+# Container status
+docker-compose -f scripts/docker/docker-compose.test.yml ps
 
-3. **Test master key directly**:
-   ```bash
-   curl -X GET \
-     -H "X-Parse-Application-Id: myAppId" \
-     -H "X-Parse-Master-Key: myMasterKey" \
-     http://localhost:1337/parse/schemas
-   ```
+# Parse Server logs
+docker logs psnext-it-server
 
-### Connection Issues
-
-```ruby
-# Test connectivity in console
-require 'test/support/test_server'
-Parse::Test::ServerHelper.setup
-Parse::Test::ServerHelper.server_available?
-```
-
-### Port Conflicts
-
-If ports 1337, 4040, or 27017 are in use, modify `docker-compose.test.yml`:
-
-```yaml
-services:
-  parse:
-    ports:
-      - "1338:1337"  # Use port 1338 instead
+# Full reset (clears volumes)
+docker-compose -f scripts/docker/docker-compose.test.yml down -v
+docker-compose -f scripts/docker/docker-compose.test.yml up -d
 ```
 
-Then update your environment variables accordingly.
-
-## Production vs Test Differences
-
-The test server configuration includes:
-- Relaxed security settings for testing
-- Auto-creation of classes
-- Verbose logging
-- Sample cloud code
-
-**Never use these settings in production!**
+### Master-key IP rejection
 
-## Status
+If you see `Request using master key rejected as the request IP address ... is
+not set in Parse Server option 'masterKeyIps'`, your client is reaching the
+server from an address outside the scoped `masterKeyIps` list above. Run the
+suite from the host (loopback) or from within the Docker network, rather than
+widening `masterKeyIps`.
 
-✅ **Working Setup**: This test server configuration has been verified to work with:
-- Parse Server 8.2.3
-- MongoDB 5.0  
-- Master key authentication for schema operations
-- Basic CRUD operations via REST API
-- Ruby Parse Stack SDK connection
-- Cloud Code execution
+### Port conflicts
 
-The setup successfully resolves Parse Server's IP restriction issues that typically prevent master key usage in Docker environments.
+Every host port is overridable via the `*_HOST_PORT` variables in the table
+above (and the matching `PARSE_TEST_*` client variable). Move both the compose
+side and the client side together so the containers and the suite agree.

data/docs/mcp_guide.md

@@ -3844,7 +3844,7 @@ Tenant scope is applied as a `$match` stage at the TOP-level pipeline only. Sub-
 2. **Refuse lookups from tenant-bound agents entirely** — application code rejects pipelines containing `$lookup` / `$graphLookup` / `$unionWith` when `agent.tenant_id` is set.
 3. **Mark joinable cross-tenant classes as `agent_hidden`** — the most permissive joining-class is unreachable to the agent.
 
-The proper fix (recursive scope injection into sub-pipelines) is tracked as a follow-up; see [SECURITY_GUIDE.md](../SECURITY_GUIDE.md) for the threat model and posture recommendations.
+The proper fix (recursive scope injection into sub-pipelines) is tracked as a follow-up; see [acl_clp_guide.md](./acl_clp_guide.md) and [SECURITY.md](../SECURITY.md) for the threat model and posture recommendations.
 
 ---
 

data/docs/mongodb_index_optimization_guide.md

@@ -645,8 +645,9 @@ explicit mappings are correct for production.
 - [mongodb_direct_guide.md](./mongodb_direct_guide.md) — the full
   direct-Mongo / index-management API reference (DSL spelling,
   writer URI, triple-gate, rake tasks)
-- [SECURITY_GUIDE.md](../SECURITY_GUIDE.md) — security posture around
-  the writer URI, role validation, audit trail
+- [acl_clp_guide.md](./acl_clp_guide.md) — security posture around
+  the writer URI, role validation, and ACL/CLP enforcement on the
+  mongo-direct path
 - MongoDB official: <https://www.mongodb.com/docs/manual/indexes/>
 - Parse Server source for auto-managed indexes:
   <https://github.com/parse-community/parse-server/blob/master/src/Adapters/Storage/Mongo/MongoStorageAdapter.js>

data/docs/usage_guide.md

@@ -626,6 +626,6 @@ end
 
 ## More Information
 
-- [CHANGELOG](./CHANGELOG.md) - Full feature history
+- [CHANGELOG](../CHANGELOG.md) - Full feature history
 - [GitHub Releases](https://github.com/neurosynq/parse-stack-next/releases) - Release notes
 - [Parse Server Docs](https://docs.parseplatform.org) - Parse Server documentation