parse-stack-next 5.1.1 → 5.2.0

data/docs/mcp_guide.md

@@ -360,6 +360,433 @@ Common uses for the direct dispatcher:
 
 ---
 
+## Connecting Claude Desktop (stdio bridge)
+
+Parse Stack speaks MCP over **HTTP** (the standalone server and the
+Rack adapter both expose a JSON-RPC-over-HTTP endpoint). Claude Desktop,
+however, launches MCP servers as local **stdio** subprocesses — it does
+not dial an HTTP URL directly. Bridge the two with
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote), a small stdio↔HTTP
+proxy that Claude Desktop runs as the subprocess and which forwards to your
+HTTP endpoint.
+
+1. Start the Parse Stack MCP endpoint over HTTP (standalone or Rack — see
+   Deployment Modes above) and note its URL and the bearer token your
+   `agent_factory` expects, e.g. `http://localhost:3001/` with
+   `Authorization: Bearer <token>`.
+
+2. Add the bridge to `claude_desktop_config.json` (macOS:
+   `~/Library/Application Support/Claude/claude_desktop_config.json`;
+   Windows: `%APPDATA%\Claude\claude_desktop_config.json`):
+
+   ```json
+   {
+     "mcpServers": {
+       "parse-stack": {
+         "command": "npx",
+         "args": [
+           "-y",
+           "mcp-remote",
+           "http://localhost:3001/",
+           "--header",
+           "Authorization: Bearer ${PARSE_MCP_TOKEN}"
+         ],
+         "env": {
+           "PARSE_MCP_TOKEN": "your-mcp-token"
+         }
+       }
+     }
+   }
+   ```
+
+3. Restart Claude Desktop. The Parse Stack tools (`query_class`,
+   `get_schema`, `semantic_search`, …) appear in the client.
+
+Notes:
+
+- `mcp-remote` requires Node.js on the machine running Claude Desktop.
+- For a public endpoint, terminate TLS in front of the HTTP server and use
+  an `https://` URL; the bearer token rides the `Authorization` header.
+- The same bridge works for any stdio-only MCP client (e.g. some IDE
+  integrations). Clients that support remote MCP connectors natively can
+  point at the HTTP URL without the bridge.
+- Approval workflows (elicitation) need the streaming/listening-stream
+  prerequisites described under Approval Workflows — confirm the bridge and
+  client forward the SSE channel before relying on human-in-the-loop gating.
+
+---
+
+## Resource Subscriptions (LiveQuery bridge)
+
+MCP lets a client `resources/subscribe` to a resource URI and then receive
+unsolicited `notifications/resources/updated` messages whenever the underlying
+data changes. Parse Stack bridges that surface onto Parse LiveQuery: a
+subscribed `parse://<Class>/count` or `parse://<Class>/samples` resource is
+backed by a LiveQuery subscription on `<Class>`, and any matching
+create/update/delete/enter/leave event is debounced into a single coarse
+update for that URI. The client re-reads the resource via `resources/read` to
+obtain the new value — row payloads are never streamed through the resource
+surface.
+
+This is opt-in and requires a streaming-capable Rack server (Puma, Falcon —
+WEBrick buffers responses and cannot hold the listening stream open) plus
+LiveQuery enabled and configured.
+
+```ruby
+# Boot: enable LiveQuery and point it at the server.
+Parse.setup(
+  server_url:     "https://your-parse-server.com/parse",
+  application_id: "your_app_id",
+  api_key:        "your_api_key",
+  live_query_url: "wss://your-parse-server.com",
+)
+Parse.live_query_enabled = true
+
+# Mount the Rack app with resource subscriptions enabled.
+app = Parse::Agent::MCPRackApp.new(resource_subscriptions: true) do |env|
+  token = env["HTTP_AUTHORIZATION"].to_s.delete_prefix("Bearer ")
+  MyAuth.agent_for_token!(token) # returns a Parse::Agent or raises Unauthorized
+end
+```
+
+When enabled and LiveQuery is available, the `initialize` handshake advertises
+`resources.subscribe: true`. When LiveQuery is not enabled/available — or on
+the WEBrick `MCPServer`, which cannot stream — the capability stays
+`subscribe: false` and `resources/subscribe` returns a "not supported" error.
+The capability is a contract: it is never advertised unless the server can
+actually deliver updates.
+
+### Protocol flow
+
+1. **`initialize`** — the response carries a server-issued `Mcp-Session-Id`
+   header. The client echoes it on every subsequent request.
+2. **`GET` listening stream** — the client opens a long-lived `GET` to the same
+   endpoint with `Accept: text/event-stream` and the `Mcp-Session-Id` header.
+   This is the server→client channel; it stays open and emits
+   `notifications/resources/updated` events until the client disconnects.
+3. **`resources/subscribe`** — a normal `POST` with
+   `{ "uri": "parse://Post/count" }`. Returns an empty result; updates begin
+   flowing on the listening stream.
+4. **`resources/unsubscribe`** — stops one subscription. `DELETE` with the
+   session id tears the whole session down.
+
+Only `count` and `samples` resources are subscribable. `schema` is rejected
+with an invalid-params error because schema changes are not LiveQuery events.
+
+### Access control (important)
+
+The bridge enforces the same scope rules as the rest of the SDK. LiveQuery
+filters events server-side using the credential on the subscribe frame, so the
+subscription's credentials are derived from the subscribing agent:
+
+| Agent scope | LiveQuery credential | Events seen |
+|-------------|----------------------|-------------|
+| session-token agent | that session token | only rows the user can read (ACL/CLP enforced by Parse Server) |
+| master-key agent | master key | every event |
+| `acl_user:` / `acl_role:` agent | **refused** | none — see below |
+
+`acl_user:` / `acl_role:` agents are an SDK-side, mongo-direct-only construct
+with no Parse Server REST or LiveQuery equivalent (Parse Server has no
+"act as this user pointer / role" handshake). Bridging them would force a
+silent downgrade to either master key (a row-level leak) or an unscoped
+session, so the bridge **fails closed** and refuses the subscription with a
+security error. Subscribe with a session-token or master-key agent instead.
+
+Because Parse Server fixes ACL-bypass authorization at LiveQuery *connect*
+time (there is no per-subscription master key), the bridge keeps two
+connections and routes by credential: master-posture subscriptions ride a
+dedicated **admin** connection
+(`Parse::LiveQuery::Client.new(use_master_key: true)`), while session-token
+subscriptions ride a normal connection and pass their token per subscription.
+Either way, an update only fires for an object the subscription's scope is
+permitted to read — LiveQuery filters events by ACL server-side. (Whether a
+master connection additionally surfaces master-key-only rows depends on the
+Parse Server version and its `masterKeyIps` configuration.)
+
+### Operational notes and limitations
+
+- **Single-process.** Subscription state lives in the `MCPRackApp` instance
+  (like the cancellation registry), so in a clustered / multi-process
+  deployment a LiveQuery event observed on one worker does not reach a
+  listening stream held on another. The delivery seam
+  (`Parse::Agent::MCPSubscriptions::Notifier`) is isolated so a Redis-backed
+  pub/sub adapter can be supplied later without changing the bridge or the
+  dispatcher; pass it via `subscription_manager:`.
+- **Subscriptions do not survive a listening-stream reconnect.** Closing the
+  `GET` stream tears down the session's LiveQuery subscriptions; a client that
+  reconnects must re-issue its `resources/subscribe` calls.
+- **Session id is a bearer capability.** The listening stream authenticates via
+  the agent factory and keys delivery off the server-issued `Mcp-Session-Id`,
+  which the client must keep secret — possession of a valid session id (plus a
+  valid agent) is sufficient to attach. This matches the cancellation model.
+- **Per-session and global caps.** A client that subscribes but never opens (or
+  later drops) its listening stream leaves LiveQuery subscriptions running until
+  the session is torn down. A per-session ceiling (default 100,
+  `max_subscriptions_per_session:` on the manager) bounds one session's
+  footprint, and a global ceiling on the number of distinct subscribing sessions
+  (default 10,000, `max_sessions:`) bounds total growth. The global cap is a
+  rejection cap (new sessions are refused with a JSON-RPC error once it is
+  reached) and fails closed.
+- **Concurrent listening streams are bounded separately from request SSE.**
+  `max_concurrent_dispatchers:` does **not**, by itself, bound the GET listening
+  streams used for resource subscriptions and notifications — those get their own
+  soft cap *equal to* `max_concurrent_dispatchers`. So the effective steady-state
+  ceiling across both surfaces is up to **2× `max_concurrent_dispatchers`** (up
+  to N request-scoped SSE dispatchers plus N listening streams). Size the value
+  with that 2× factor in mind (e.g. relative to your Puma `max_threads`). Leaving
+  it unset (the default `nil`) leaves both surfaces uncapped; the app logs a
+  one-time warning at construction when a streaming or subscription/notification
+  surface is enabled without a cap.
+
+---
+
+## Approval Workflows (MCP elicitation)
+
+`:write` / `:admin` tier tool calls can require human approval before they run,
+using the MCP 2025-06-18 spec-native `elicitation/create` channel. Off by
+default, so existing clients are unaffected.
+
+```ruby
+# Opt tiers in (process-wide). Has teeth only when an approval gate is installed
+# (the MCP transport installs one per session; see below).
+Parse::Agent.require_approval_for = [:write, :admin]
+```
+
+The approval gate is a pluggable `agent.approval_gate` consulted inside
+`Parse::Agent#execute` — so it is reachable on the non-MCP path and
+unit-testable with a fake approver. `Parse::Agent::MCPElicitationGate` is the
+spec-native implementation; `Parse::Agent::NullGate` (the default) approves.
+
+Round-trip over the streaming transport:
+
+1. A `tools/call` for a gated tier pauses before execution. The server builds an
+   `elicitation/create` request whose payload carries the **approval preview**
+   (for `call_method` the *effective* tier is resolved from the target
+   `agent_method`'s declared permission, so write/admin methods invoked through
+   the readonly `call_method` tool are gated correctly). The preview is a real
+   before/after only for methods that declare `supports_dry_run`; for the
+   built-in `update_object` / `delete_object` it is the proposed `{ tool, args }`
+   call, **not** a fetched before/after of the target row.
+2. The request is pushed to the client over the open **GET listening stream**
+   (the same bus as resource subscriptions).
+3. The client replies with a JSON-RPC response (`{ result: { action: "accept" |
+   "decline" | "cancel" } }`) as a separate POST. The server routes it,
+   session-bound, into a pending registry that wakes the blocked tool thread.
+4. `accept` → the tool runs. Anything else → a structured refusal; the tool
+   never executes.
+
+Client capability + transport requirements (the server READS, does not
+advertise, the client's `elicitation` capability at `initialize`):
+
+```ruby
+Parse::Agent::MCPRackApp.new(
+  streaming: true,
+  resource_subscriptions: true,   # or notifications: true — either opens the GET bus
+  approval_timeout: 300,          # seconds to wait for a human; default 300
+  agent_factory: ->(env) { ... },
+)
+```
+
+**Three prerequisites — miss any one and every gated write fails closed,
+which looks like a bug rather than a config gap:**
+
+1. **`streaming: true`** on the `MCPRackApp` (it defaults to `false`). Approval
+   needs a server→client request, which only the streaming transport can send.
+2. **An open GET bus** — `notifications: true` *or* `resource_subscriptions:
+   true`. `notifications: true` is the lighter choice if you don't need
+   LiveQuery resource subscriptions. Without a bus there is no channel to
+   deliver `elicitation/create`.
+3. **A concurrent server (Puma), not the bundled `MCPServer`.** The bundled
+   server runs on WEBrick and is non-streaming, so approval can never round-trip
+   there — mount {Parse::Agent.rack_app} under Puma for any deployment that uses
+   approval.
+
+Operator aid: a write/admin agent served over MCP with `require_approval_for`
+empty emits a one-time `[Parse::Agent:SECURITY]` warning (writes run ungated).
+Approval round-trips also emit a `parse.agent.approval` `ActiveSupport::Notifications`
+event carrying `outcome`, `reason`, and the measured wait — subscribe to it to
+spot a non-answering client holding a dispatcher thread for the full
+`approval_timeout` (default 300s).
+
+**Fails closed.** When approval is required but the client did not advertise the
+`elicitation` capability, no listening stream is open, the transport is
+non-streaming (WEBrick), or the approver times out, the destructive operation is
+**refused** — never blocked forever, never silently executed. Replies are bound
+to the answering session's `Mcp-Session-Id`, so one session cannot answer (or
+guess the id of) another's prompt.
+
+---
+
+## Server-initiated Notifications (general purpose)
+
+The GET listening-stream bus also backs arbitrary server→client notifications,
+without requiring LiveQuery resource subscriptions:
+
+```ruby
+app = Parse::Agent::MCPRackApp.new(streaming: true, notifications: true,
+                                   agent_factory: ->(env) { ... })
+
+# From application code that holds the app reference:
+app.notify("the-session-id", method: "notifications/custom", params: { foo: 1 })
+```
+
+`notifications: true` builds the listening-stream manager in a `supported:
+false` posture: the GET stream and `#notify` work, but `resources.subscribe`
+stays unadvertised and `resources/subscribe` POSTs fail closed. `#notify` builds
+a JSON-RPC **notification** (never an `id` — that distinguishes it from the
+server-initiated *request* used by elicitation) and returns `false` when no
+stream is attached for the session. `app.subscription_manager` is exposed for an
+out-of-band / clustered publisher that needs the lower-level `publish` seam.
+
+---
+
+## Built-in Agent Hardening & Telemetry
+
+5.2 adds several agent-side controls, all configured on `Parse::Agent`:
+
+- **Impersonation** — `Parse::Agent.new(impersonate_user: <id|Pointer|User>,
+  impersonate_mint: false, impersonation_label:)` (or `agent.impersonate(user)`
+  / `agent.stop_impersonating!`) resolves a real session token for a `_User`
+  (reusing an active `_Session`, or minting a restricted one with
+  `impersonate_mint: true`) and binds it as if `session_token:` had been passed.
+  Master-key client required; fails closed if no session resolves. An
+  `impersonation_label:` (also usable with `acl_role:`) is emitted on the
+  `parse.agent.tool_call` payload alongside `impersonated_user_id`.
+- **Prompt hardening** (`Parse::Agent::PromptHardening`) — schema descriptions
+  surfaced by `get_schema` / `get_all_schemas` are sanitized (non-identifier
+  field names dropped with a `[Parse::Agent:PROMPT]` warning, control/zero-width
+  chars stripped, capped, marker-wrapped); untrusted tool content has embedded
+  wrapper markers neutralized (`Parse::Agent.prompt_marker_strict = true` to
+  refuse instead). Operator canary phrases via
+  `Parse::Agent.prompt_injection_canaries = ["IGNORE PREVIOUS", /system:/i]`
+  emit `parse.agent.prompt_injection_detected`; set
+  `Parse::Agent.canary_action = :refuse` to raise on a hit.
+  `Parse::Agent::PROMPT_VERSION` is surfaced via
+  `agent.describe[:prompt][:version]`. A one-time warning fires when
+  `allowed_llm_endpoints` is left unrestricted (nil).
+- **Embedding-cost telemetry** — embedding calls made inside a tool span add
+  `embed_calls`, `embed_tokens`, and (when
+  `Parse::Agent.embed_cost_per_million_tokens` is set) `embed_cost_usd` to the
+  `parse.agent.tool_call` payload. The per-tool span does **not** cover
+  corpus/ingestion embeds fired at `Model.save` time (typically the dominant
+  spend) — wrap those in `Parse::Agent.measure_embeddings { … }`, which returns
+  `{ calls:, tokens:, cost_usd: }` for the work done on the calling thread:
+
+  ```ruby
+  stats = Parse::Agent.measure_embeddings do
+    KnowledgeArticle.save_all(batch)   # embed-on-save
+  end
+  stats # => { calls: 1200, tokens: 4_300_000, cost_usd: 0.43 }
+  ```
+
+  Thread-local: embeds fanned out to other threads/fibers are not captured —
+  measure inside each worker. `Parse::Agent.embed_cost_usd(tokens)` converts a
+  token count to USD using the configured rate (nil when unset).
+- **Provenance** — `Parse::Agent.include_source_provenance = true` (default
+  false) stamps each read-tool row with `_source = { class, tool, object_id }`,
+  applied after field-allowlist projection and redaction.
+- **`semantic_search` tool** — registered readonly + `client_safe`; opt a model
+  in with `agent_searchable field:, filter_fields:`. See the
+  [Atlas Vector Search Guide](./atlas_vector_search_guide.md#retrieval-rag).
+
+### Runtime denial gates
+
+Beyond the permission-tier and env-gate checks, several gates refuse a tool
+call at runtime based on its arguments. They fail closed; a caller sees a
+structured error (the built-in tools return `{ success: false, error:,
+error_code: }`, which surfaces as `isError: true` over MCP). Knowing them up
+front avoids discovering each only on impact:
+
+| Gate | When it fires | Surfaced as |
+|------|---------------|-------------|
+| Missing tenant scope | A searchable class has no `agent_tenant_scope` while other classes do (tenant-aware deployment) | `Parse::Agent::MissingTenantScope` (search path); a one-time `[Parse::Agent:SECURITY]` lint warning on the general query path |
+| No tenant binding | A scoped class is queried by an agent whose tenant value resolves to `nil` | `Parse::Agent::AccessDenied` (`kind: :tenant`) |
+| Hidden class | A tool targets an `agent_hidden` class (or one outside a per-instance `classes:` allowlist) | `Parse::Agent::AccessDenied` (`kind: :hidden_class`) / off-allowlist refusal |
+| Reserved underscore key | A `filter:` / `vector_filter:` / `where:` contains an underscore-prefixed key (`_rperm`, `_p_*`, …) at any depth | `ArgumentError` / `ValidationError` (recursive refusal) |
+| Filter-field allowlist | A `filter:` / `vector_filter:` names a field not in the class's `agent_searchable filter_fields:` | `ValidationError` naming the offending field(s) |
+| `text_field` not embedded | `semantic_search` `text_field:` names a field that isn't a declared `embed` source | `ValidationError` listing the allowed sources |
+| Tool filtered | A tool/method removed by a per-instance `tools:` / `methods:` filter is invoked | `error_code: :tool_filtered` |
+| Approval denied/unavailable | A gated write/admin op is rejected or the approver is unreachable | `error_code: :approval_denied` |
+
+---
+
+## Token Economy
+
+The MCP surface is paid for in LLM context tokens — the tool schemas sent every
+session, and the data every tool returns. 5.2 adds controls to keep that cost
+down.
+
+### Lean tool profile
+
+A full `:readonly` `tools/list` payload is roughly **7.9K context tokens** every
+session. For small-context models or token-sensitive deployments, the `:lean`
+profile narrows the surface to the six core read tools (`get_all_schemas`,
+`get_schema`, `query_class`, `count_objects`, `get_object`, `aggregate`) —
+about **2.6K tokens, a ~67% reduction**:
+
+```ruby
+Parse::Agent.new(permissions: :readonly, tools: :lean)
+```
+
+A profile is an allowlist: it composes with the permission tier and can only
+narrow, never elevate. Profiles are Symbol-only (`Parse::Agent::TOOL_PROFILES`);
+for finer control still pass an explicit Array or `{ only:, except: }`. An
+unknown profile raises rather than silently exposing the full surface.
+
+### Leaner tool responses
+
+Read tools return rows in an LLM-friendly form (Pointers as `{_type, class,
+id}`, Dates as bare ISO strings) and now **strip the raw `ACL` map** — it is
+operationally useless to a model (effective authority is enforced server-side
+regardless) and is pure token overhead plus a minor role/user-id disclosure.
+`get_objects` and the Atlas Search tools now go through the same normalization
+`query_class` always used, instead of shipping raw wire-form.
+
+Defaults that bound response size: `query_class` `limit:` defaults to 100 (cap
+1000) with the rendered array capped at 50 (`truncated_note`); `aggregate`
+auto-injects a terminal `$limit: 200`. Pass a smaller `limit:` / project fewer
+fields via `keys:` when you want a tighter result.
+
+### `semantic_search` — deduped sources and a token budget
+
+The `semantic_search` result hoists each chunk's parent record **once** into a
+`documents` map keyed by `objectId`, instead of duplicating the full source on
+every chunk — map a chunk back to its source via `metadata.object_id`:
+
+```jsonc
+{
+  "chunks": [
+    { "id": "a#0", "score": 0.82, "content": "…", "metadata": { "object_id": "a", "chunk_index": 0 } },
+    { "id": "a#1", "score": 0.82, "content": "…", "metadata": { "object_id": "a", "chunk_index": 1 } }
+  ],
+  "documents": { "a": { "objectId": "a", "title": "…" } },
+  "count": 2
+}
+```
+
+A `max_total_tokens` budget (default 20,000; estimated as chars/4) trims the
+lowest-ranked chunks so a few long documents can't silently blow the context
+window — the count caps (`k * max_chunks_per_document`) bound the chunk *count*
+but not their total size. When the budget trims, the result adds
+`budget_truncated: true` and `budget_dropped: <n>` so the truncation is never
+silent. Pass `max_total_tokens: 0` to disable.
+
+### Structured error metadata on the wire
+
+A failing `tools/call` already carries `error_code` and a structured `details:`
+hash (e.g. `allowed_fields`, `suggested_rewrite`) and `retry_after` — these are
+now forwarded on the MCP error envelope under `_meta` (`parse.error_code`,
+`parse.retry_after`, `parse.details`) so a client can branch deterministically
+and honor `retry_after` instead of re-parsing the prose message. The
+human-readable `content` text is unchanged.
+
+`get_schema` on a mistyped class name now raises a `ValidationError` carrying a
+"Did you mean: …?" hint (near matches from the locally-known classes), so the
+model self-corrects in one retry instead of falling back to a full
+`get_all_schemas` sweep.
+
+---
+
 ## Custom Authentication
 
 The agent factory pattern gives you full control over authentication. Every request passes through the factory before any Parse operation is attempted.
@@ -739,6 +1166,10 @@ agent = Parse::Agent.new(tools: { only: [:query_class, :get_schema, :aggregate],
 
 # Denylist only
 agent = Parse::Agent.new(tools: { except: [:emit_artifact] })
+
+# Named profile (Symbol) — :lean narrows to the six core read tools
+# (~67% smaller tools/list). See "Token Economy" above.
+agent = Parse::Agent.new(tools: :lean)
 ```
 
 **Resolution order** is strict: env-gates ▷ permission tier ▷ per-instance filter. The filter cannot elevate — `tools: { only: [:delete_object] }` on a `:readonly` agent still excludes `delete_object` because `delete_object` is not in the readonly tier's permitted set in the first place.
@@ -1667,6 +2098,8 @@ Known `details[:kind]` subcodes for `:access_denied`:
 
 The top-level `error_code` stays at `:access_denied` for back-compat with consumers that only branch on it. The new subcode is purely additive — clients that ignore `details:` see no change in behavior.
 
+**On the wire (5.2+):** `error_code`, `retry_after`, and `details` are forwarded on the MCP tool-error envelope under `_meta` — `parse.error_code`, `parse.retry_after`, `parse.details` — so a spec-compliant client can branch deterministically (and honor `retry_after`) without parsing the prose `content` text. The `content` text and `isError: true` are unchanged.
+
 ---
 
 ## Performance and Timeouts

data/docs/mongodb_direct_guide.md

@@ -757,6 +757,15 @@ non-master scope so this enforcement always runs. See the
 [Atlas Vector Search Guide](./atlas_vector_search_guide.md) for the
 full API surface.
 
+`Parse::Retrieval.retrieve` and the `semantic_search` agent tool (v5.2)
+build directly on `find_similar`, so they inherit this exact Layer 1-5
+mongo-direct enforcement. The earlier RAG plan's "two-stage" REST
+re-query was intentionally NOT adopted — there is no REST vector path,
+and `acl_user:` / `acl_role:` scopes have no REST equivalent, so the
+post-`$vectorSearch` `_rperm` `$match` is the single enforcement
+boundary. The retrieval layer adds a tenant-scope fold into the Atlas
+pre-filter on top of this, never a substitute for it.
+
 ### Timeouts
 
 ```ruby
@@ -947,7 +956,7 @@ three independent flags that every mutation re-checks per call.
   Requires `clusterMonitor` privilege on the reader; returns `{}`
   when not granted so callers degrade gracefully.
 
-### Model DSL: `mongo_index` / `mongo_geo_index` / `mongo_relation_index`
+### Model DSL: `mongo_index` / `unique_index_on` / `mongo_geo_index` / `mongo_relation_index`
 
 Index declarations are class-level metadata on `Parse::Object`
 subclasses. They run validation at registration time so a typo,
@@ -967,6 +976,7 @@ class Car < Parse::Object
 
   mongo_index :make, :model, :year         # compound
   mongo_index :vin, unique: true
+  unique_index_on :registration            # dedup floor; unique { registration: 1 }
   mongo_index :owner                       # pointer auto-rewrites to _p_owner
   mongo_geo_index :location                # 2dsphere on GeoJSON Point
   mongo_index :tags                        # array field
@@ -1007,6 +1017,61 @@ class Author < Parse::Object
 end
 ```
 
+### `unique_index_on` — the `first_or_create!` correctness floor
+
+`unique_index_on(*fields, sparse: false, partial: nil, name: nil)` declares
+a unique index on the exact dedup tuple that `first_or_create!` and
+`create_or_update!` key on. It is thin sugar over
+`mongo_index(*fields, unique: true, …)` — same registration, same validation
+(sensitive-field guard, pointer auto-rewrite, parallel-array / relation /
+`_id` rejection), same `apply_indexes!` writer path — but the name states the
+intent: these fields are the create-or-update identity.
+
+```ruby
+class Subscription < Parse::Object
+  property :email, :string
+  belongs_to :tenant, as: :user
+
+  unique_index_on :email, :tenant   # key: { email: 1, _p_tenant: 1 } unique
+end
+
+Subscription.apply_indexes!          # provisions the index via the writer gate
+```
+
+**Why it matters.** The Redis-backed `synchronize:` lock on `first_or_create!`
+is a *latency optimization*: in the common path it collapses concurrent
+callers so only one issues the create. The unique index is the *correctness
+floor* that survives the lock being bypassed — a Redis outage, a TTL expiring
+between the existence check and the write, a caller passing
+`synchronize: false`, or two app servers whose lock secrets disagree. When a
+race slips past the lock, the loser's insert fails with `DuplicateValue`
+(Parse error 137), which `first_or_create!` rescues and resolves to the
+winning row. Lock plus index make the net invariant — *exactly one row, every
+caller sees the same id* — hold under any race, not just the happy path.
+
+**Defaults are non-sparse, on purpose.** The index key is kept identical to
+the query `first_or_create!` re-runs on recovery (`_scoped_first` on the same
+`query_attrs`), so a 137 always corresponds to a row the recovery query can
+find. A sparse or partial index that fires on a condition the recovery query
+doesn't reproduce would surface a 137 the rescue can't resolve, and the error
+would re-raise. `sparse:` only changes behavior for a document missing *every*
+field in the tuple — a compound sparse index indexes a doc when it has at
+least one key, and `first_or_create!` always writes the full tuple, so sparse
+never weakens the floor. Leave it off unless out-of-band writers create
+tuple-less rows you want excluded.
+
+For "unique within a subset" — unique email per tenant, but rows with no
+tenant may repeat — a partial filter is the right tool, **not** `sparse:`
+(a compound sparse index still collides two rows that share the present
+fields). You own the filter's lifecycle and must keep the recovery query
+consistent with it:
+
+```ruby
+# Unique email per tenant; tenant-less rows are not constrained.
+unique_index_on :email, :tenant,
+                partial: { "_p_tenant" => { "$exists" => true } }
+```
+
 ### Migrator: `indexes_plan` (dry-run) / `apply_indexes!` (mutate)
 
 `Parse::Schema::IndexMigrator` reconciles declared indexes against the

data/docs/mongodb_index_optimization_guide.md

@@ -66,6 +66,7 @@ paying for an index nobody uses.
 | Regular B-tree | `mongo_index :field` | Equality, range, sort on a scalar field |
 | Compound | `mongo_index :a, :b, :c` | Multi-field queries with a common prefix |
 | Unique | `mongo_index :field, unique: true` | Enforce uniqueness at the DB layer |
+| Unique dedup floor | `unique_index_on :a, :b` | Name the `first_or_create!` / `create_or_update!` dedup tuple; sugar for `unique: true` (non-sparse) |
 | Sparse | `mongo_index :field, sparse: true` | Field present on only some documents |
 | Partial | `mongo_index :field, partial: { … }` | Index only documents matching a filter |
 | TTL | `mongo_index :field, expire_after: N` | Auto-delete documents N seconds after the timestamp |
@@ -318,7 +319,27 @@ fails.
 
 **Better:** `unique: true, sparse: true` for "unique when present".
 This is exactly what `parse_reference` auto-registers, and it's the
-right pattern for any optional uniqueness constraint.
+right pattern for any optional uniqueness constraint *on a single
+field*.
+
+**Sparse does NOT generalize to compound keys.** A compound sparse
+index excludes a document only when it is missing *every* indexed
+field; a document that has at least one key is still indexed. So for a
+two-field tuple, two rows that share the present field and both omit
+the other still collide under `sparse: true`. For "unique within a
+subset" — e.g. unique `email` per `tenant`, but tenant-less rows may
+repeat — use a **partial filter**, not sparse:
+
+```ruby
+unique_index_on :email, :tenant,
+                partial: { "_p_tenant" => { "$exists" => true } }
+```
+
+For the `first_or_create!` / `create_or_update!` dedup tuple, prefer
+`unique_index_on` (sugar for `unique: true`, **non-sparse** by default
+so the index key matches the query the upsert re-runs on recovery). It
+is the durable correctness floor behind the synchronize-create lock —
+see the MongoDB Direct guide for the full rationale.
 
 ### Geo without proper coordinate order
 

data/docs/usage_guide.md

@@ -133,6 +133,21 @@ song = Song.first_or_create!({ title: "My Song" }, { artist: "Unknown" })
 song = Song.create_or_update!({ title: "My Song" }, { plays: 100 })
 ```
 
+Under concurrency these have a TOCTOU window. Pass `synchronize: true` to
+serialize the find→create→save through a Moneta-backed lock, and declare a
+`unique_index_on` on the dedup tuple as the durable correctness floor — the lock
+optimizes latency, the unique index guarantees a single row even if the lock is
+bypassed:
+
+```ruby
+class Song < Parse::Object
+  property :title, :string
+  unique_index_on :title          # provisioned via Song.apply_indexes!
+end
+
+Song.first_or_create!({ title: "My Song" }, { artist: "Unknown" }, synchronize: true)
+```
+
 ## ACLs (Access Control)
 
 ```ruby