parse-stack-next 5.8.0 → 5.8.2

data/README.md

@@ -3069,8 +3069,13 @@ songs.save
 
 # you can also destroy a set of objects
 songs.destroy
+
+# send every write as a specific user (ACL and CLP enforced)
+songs.save(session: user)
 ```
 
+Each write in a batch keeps the credentials it was built for. Parse Server runs a `POST /batch` under one credential, so objects whose classes use clients with different credentials (for example a class bound to `Parse.client.become(token)`; identically configured clients are merged), or raw `Parse::Request`s carrying different `session_token:` or `use_master_key:` options, are sent as separate batch calls, each with its own credentials. Responses still come back in request order.
+
 ### Magic `save_all`
 By default, all Parse queries have a maximum fetch limit of 1000. While using the `:max` option, Parse-Stack can increase this up to 11,000. In the cases where you need to update a large number of objects, you can utilize the `Parse::Object#save_all` method to fetch, modify and save objects.
 
@@ -3131,6 +3136,7 @@ end
 - **Mixed operations**: Support create, update, and delete operations in single transaction
 - **Error handling**: Comprehensive error handling with meaningful exception messages
 - **Object ID assignment**: New objects automatically receive their `objectId`, `createdAt`, and `updatedAt` from the server response after successful transaction
+- **One credential**: A transaction runs with the credentials of its objects' class client, or as a given user with `Parse::Object.transaction(session: user)`. Objects bound to clients with different credentials raise `Parse::BatchOperation::MixedAuthorityError` before anything is sent, because a transaction cannot be split.
 
 ```ruby
 # Transaction with custom retry limit and error handling
@@ -3873,8 +3879,8 @@ If you want to see if a particular field contains a specific Parse::Object (poin
 q.where :field => Parse::Pointer.new("_User", "anObjectId")
 # alias using subclass helper
 q.where :field => Parse::User.pointer("anObjectId")
-# alias using `:id` constraint. We will infer :user maps to class "_User" (Parse::User)
-q.where :user.id => "anObjectId"
+# alias using the `pointer_id` constraint. We will infer :user maps to class "_User" (Parse::User)
+q.where :user.pointer_id => "anObjectId"
 ```
 
 #### Less Than
@@ -3976,15 +3982,15 @@ Match arrays by their length:
 
 ```ruby
 # Exact size
-q.where :tags.size => 2          # arrays with exactly 2 elements
+q.where :tags.array_size => 2                  # arrays with exactly 2 elements
 
 # Size comparisons
-q.where :tags.size => { gt: 3 }      # size > 3
-q.where :tags.size => { gte: 2 }     # size >= 2
-q.where :tags.size => { lt: 5 }      # size < 5
-q.where :tags.size => { lte: 4 }     # size <= 4
-q.where :tags.size => { ne: 0 }      # size != 0
-q.where :tags.size => { gte: 2, lt: 10 }  # range: 2 <= size < 10
+q.where :tags.array_size => { gt: 3 }          # size > 3
+q.where :tags.array_size => { gte: 2 }         # size >= 2
+q.where :tags.array_size => { lt: 5 }          # size < 5
+q.where :tags.array_size => { lte: 4 }         # size <= 4
+q.where :tags.array_size => { ne: 0 }          # size != 0
+q.where :tags.array_size => { gte: 2, lt: 10 } # range: 2 <= size < 10
 
 # Empty/non-empty shortcuts (index-friendly)
 q.where :tags.arr_empty => true     # empty arrays (uses { field: [] })
@@ -4033,7 +4039,7 @@ All array constraints work with `has_many :through => :array` relations:
 Product.query(:categories.set_equals => [cat1, cat2])
 
 # Find products with more than 3 categories
-Product.query(:categories.size => { gt: 3 })
+Product.query(:categories.array_size => { gt: 3 })
 ```
 
 **Note:** Array constraints using aggregation pipelines require MongoDB 3.6+.
@@ -4213,7 +4219,7 @@ Event.where(:updated_at.between_dates => [1.week.ago, Time.now])
 ```
 
 #### Matches Object Id
-Sometimes you want to find rows where a particular Parse object exists. You can do so by passing a the Parse::Object subclass or a Parse::Pointer. In some cases you may only have the "objectId" of the record you are looking for. For convenience, you can also use the `id` constraint. This will assume that the name of the field matches a particular Parse class you have defined. Assume the following:
+Sometimes you want to find rows where a particular Parse object exists. You can do so by passing a the Parse::Object subclass or a Parse::Pointer. In some cases you may only have the "objectId" of the record you are looking for. For convenience, you can also use the `pointer_id` constraint. This will assume that the name of the field matches a particular Parse class you have defined. Assume the following:
 
 ```ruby
 # where this Parse object equals the object in the column `field`.
@@ -4221,18 +4227,18 @@ q.where :field => Parse::Pointer("Field", "someObjectId")
 # => "field":{"__type":"Pointer","className":"Field","objectId":"someObjectId"}}
 
 # alias, shorthand when we infer `:field` maps to `Field` parse class.
-q.where :field.id => "someObjectId"
+q.where :field.pointer_id => "someObjectId"
 # => "field":{"__type":"Pointer","className":"Field","objectId":"someObjectId"}}
 
 ```
 It is always important to be thoughtful in naming column names in associations as
 close to their foreign Parse class names. This enables more expressive syntax while reducing
-code. The `id` also supports any object or pointer object. These are all equivalent:
+code. `pointer_id` also accepts any object or pointer object. These are all equivalent:
 
 ```ruby
 q.where :user    => User.pointer("xyx123")
-q.where :user.id => "xyx123"
-q.where :user.id => User.pointer("xyx123")
+q.where :user.pointer_id => "xyx123"
+q.where :user.pointer_id => User.pointer("xyx123")
 # All produce
 # => "user":{"__type":"Pointer","className":"_User","objectId":"xyx123"}}
 ```
@@ -4260,15 +4266,15 @@ In some cases, you do not have the Parse object, but you have its `objectId`. Yo
 
 ```ruby
 # shorthand if you are using convention. Will infer class `Artist`
-Song.all :artist.id => artist_id
+Song.all :artist.pointer_id => artist_id
 
 # other approaches, same result
 Song.all :artist => Artist.pointer(artist_id)
 Song.all :artist => Parse::Pointer.new("Artist", artist_id)
 
-# "id" safely pointers and strings for supporting these types of API patterns
+# `pointer_id` safely accepts pointers and strings for these kinds of API patterns
 def find_songs(artist)
-  Song.all :artist.id => artist
+  Song.all :artist.pointer_id => artist
 end
 
 # all ok
@@ -5813,7 +5819,7 @@ Event.query(:event_date.gt => Time.now).results_direct
 Event.query(:event_date.gte => start_date, :event_date.lte => end_date).results_direct
 
 # Array operators
-Song.query(:tags.size => 3).results_direct
+Song.query(:tags.array_size => 3).results_direct
 Song.query(:tags.contains_all => ["rock", "classic"]).results_direct
 Song.query(:tags.empty_or_nil => true).results_direct
 
@@ -6101,6 +6107,12 @@ Parse.client.authorization.invalidate(token)
 Parse.client.authorization.invalidate_user_roles(user_id)
 ```
 
+A custom identity plane that implements neither `invalidate_value` nor
+generation support (`generation`, `generation_current?`, `bump_generation`)
+can only forget one token at a time. Revoking every session
+of a user (password change, account deletion, `logout_all!`, a batch destroy of
+sessions) is then bounded by `identity_cache_ttl` rather than immediate.
+
 Both caches default to per-process memory. With a keyspaced
 `Parse::Cache::Redis` you can move them to the shared backend so every worker
 resolves against the same view, and let webhook triggers invalidate them

data/docs/caching.md

@@ -230,6 +230,38 @@ caching path the two never meet. Three points are worth knowing anyway.
 
 ## Auth scoping of cached responses
 
+### Session reads are not cached by default
+
+A read made with a session token is never read from or stored in the response
+cache unless the application opts in:
+
+```ruby
+Parse::Middleware::Caching.cache_session_requests = true   # every client
+Parse.setup(cache_session_requests: true, ...)            # one client
+```
+
+Only `true` enables it (a `"true"` String from an environment variable does
+not). A client's own `cache_session_requests:` option overrides the class
+default in either direction.
+
+A cached answer is served without contacting Parse Server, so it cannot notice
+that the session was revoked (logout, `Parse::Session#destroy`, `logout_all!`,
+a password change) or that the user lost a role or row access through a change
+this process did not make. With the default, every REST session read reaches
+Parse Server, which checks the token and the current ACLs and CLPs each time.
+Mongo-direct reads, including agent tools that route there, do not go through
+this cache; they resolve the session through the identity plane, whose
+revocation behavior is described in
+[Identity and role caching](#identity-and-role-caching). This
+applies however the session reached the request: an explicit `session_token:`,
+`Parse.with_session`, or a client bound to a session. Master-key and
+anonymous reads cache as before, and writes made with a session still
+invalidate cached entries. Turning the option on trades that guarantee for
+speed: a revoked or narrowed session keeps reading its cached responses until
+they expire, so keep `expires:` short if you enable it.
+
+### The auth discriminator
+
 The cache key carries an auth discriminator, and this is a correctness property
 rather than an optimization.
 
@@ -251,9 +283,9 @@ URL digest is placed before the discriminator, so every auth variant of one
 resource shares a prefix, which is exactly what lets a write invalidate the
 resource for all callers with a single pattern delete.
 
-One consequence worth planning for: a heavily multi-user endpoint produces one
-cache entry per session per URL. Cardinality scales with active sessions, not
-with distinct resources.
+One consequence worth planning for, once session caching is enabled: a heavily
+multi-user endpoint produces one cache entry per session per URL. Cardinality
+scales with active sessions, not with distinct resources.
 
 ## Identity and role caching
 
@@ -358,6 +390,56 @@ Two behaviors to know before you rely on these:
   triggers depend on. The deprecated `Parse::AtlasSearch::Session.invalidate` /
   `.invalidate_user_roles` forms still work through 5.x: they delegate to the
   default client's context, so they can only ever address `Parse.client`.
+* A custom identity plane you write yourself needs `get`, `set`, and
+  `invalidate`. Revoking one token (logout, `Parse::Session#destroy` on a
+  session that carries its token) works with those alone. Revoking every token
+  of a user (password change, account deletion, `logout_all!`, destroying a
+  session fetched without its token, or a batch `Array#destroy` of sessions or
+  users) also needs either `invalidate_value(user_id)` or generation support
+  (`generation`, `generation_current?`, and `bump_generation`), because the
+  plane is keyed by token. A plane with neither keeps resolving
+  those tokens until their cached entries expire, so revocation there is
+  bounded by `identity_cache_ttl`, not immediate. Lower the TTL if that window
+  is too long.
+* A session or user delete drops its cached identity when the delete succeeds
+  or reports the row already gone ("object not found"); a denied delete leaves
+  the cache alone. A session fetched without its token is looked up first
+  (with the master key when the client has one, otherwise with the delete's
+  `session:`). When the lookup finds no row (the session is already gone or
+  not visible), the delete uses the owner recorded when a `_Session` query or
+  `Parse::Session.session` last fetched that session through the same client.
+  Only the owner's user id is recorded, never the token, for as long as an
+  identity entry lives. The records sit in their own store
+  (`client.authorization.session_owner_cache`, process-local by default, set
+  a shared store to share them), never in the identity plane, so no session
+  token can read one. With no
+  recorded owner, a batch delete that reports the row deleted or "object not
+  found" clears the client's identity and role cache, and so does a lookup
+  that fails outright. Either reset happens at most once every 5 seconds per
+  client, so an endpoint that deletes caller-supplied session ids cannot flush
+  a shared plane on every request. A single `destroy` cannot tell "already
+  gone" from "denied", so it uses the recorded owner but never resets. The
+  residual window is a session deleted elsewhere whose owner this process
+  never recorded: its cached token resolves until the next reset or until
+  `identity_cache_ttl`.
+* A token resolution that is in flight when an invalidation lands does not
+  cache its answer, so it cannot put a just-revoked token back. Every
+  invalidation moves a marker before it drops entries, and the resolver
+  checks the marker before writing and again after, evicting its own write
+  when it moved. On the Redis identity plane the marker is a random nonce
+  shared by every process, replaced on each invalidation, so this also holds
+  for invalidations made by other processes, including a full reset. A custom
+  plane gets the same cross-process guarantee by implementing
+  `invalidation_nonce` (return the current marker String, or nil when none is
+  set) and `bump_invalidation_nonce` (store and return a new random String).
+  A custom plane with generation support but no nonce shares a generation
+  counter instead. That covers single-token and per-user invalidations made
+  by other processes, but not a full reset if the plane's `clear` also deletes
+  its generation counters: the counter restarts at a value an in-flight
+  lookup may already hold, so a lookup racing another process's reset can
+  keep its answer until `identity_cache_ttl`. A plane with neither gets the
+  guarantee within one process only, and across processes it is bounded by
+  `identity_cache_ttl`.
 
 On a Redis outage these planes behave differently from the response cache.
 The response cache degrades to a passthrough request; the identity and role
@@ -653,8 +735,10 @@ Work down this list.
    so deliberately.
 5. Is this a `fetch!` or `reload!`? Those default to write-only mode, which by
    design never reads from the cache. Use `fetch_cache!` to accept a cached body.
-6. Is the caller a different session? Entries are not shared across auth
-   identities, so the first request for each session is always a miss.
+6. Is the read made with a session token? Session reads bypass the cache
+   unless `Parse::Middleware::Caching.cache_session_requests = true`. With it
+   on, entries are not shared across auth identities, so the first request for
+   each session is always a miss.
 7. Is the store process-local? A Moneta memory store behind several workers hits
    only when the same worker handles the repeat.
 8. Has something set `Parse::Middleware::Caching.enabled = false`? That is the
@@ -675,6 +759,7 @@ All events are `ActiveSupport::Notifications`.
 | `parse.cache.store` | the same, plus `duration_ms` |
 | `parse.cache.delete` | the same, emitted on an invalidating write |
 | `parse.cache.error` | the same, plus `error` (the exception class name only) |
+| `parse.cache.bypass` | the same, plus `reason: :session` for a session read kept out of the cache |
 | `parse.cache.evict` | `pattern_digest`, `deleted`, `duration_ms` |
 | `parse.synchronize_create.acquired` | `key_digest`, `wait_ms` |
 | `parse.synchronize_create.contended` | `key_digest`, `elapsed_ms` |

data/docs/mcp_guide.md

@@ -880,6 +880,15 @@ The approval gate is a pluggable `agent.approval_gate` consulted inside
 unit-testable with a fake approver. `Parse::Agent::MCPElicitationGate` is the
 spec-native implementation; `Parse::Agent::NullGate` (the default) approves.
 
+A sub-agent built with `parent:` and no gate of its own uses its parent's gate,
+read at call time, so the gate the dispatcher installs on the parent for a
+`tools/call` also covers any sub-agent a tool builds during that call. Before
+5.8.1 a sub-agent fell back to `NullGate` and skipped approval. Assigning a
+gate on the sub-agent itself overrides this, and assigning `nil` removes the
+override so the sub-agent uses its parent's gate again. The dispatcher
+snapshots and restores the agent's own gate (`approval_gate_override`), so
+driving a sub-agent through `tools/call` never pins its parent's gate onto it.
+
 Round-trip over the streaming transport:
 
 1. A `tools/call` for a gated tier pauses before execution. The server builds an
@@ -1646,7 +1655,7 @@ agent = Parse::Agent.new(methods: [:archive, "Project.set_client_description"])
 agent = Parse::Agent.new(methods: { except: ["Account.delete_account"] })
 ```
 
-Entries are bare method names (`:archive` — matches the method on any class) or qualified names (`"Project.archive"` — matches only on that class). Both forms coexist in the same Set; matching is an OR.
+Entries are bare method names (`:archive`, which matches the method on any class) or qualified names (`"Project.archive"`, which matches only on that class). Both forms coexist in the same Set; matching is an OR. The class part is compared by its Parse class name, so `"User.reset"` and `"_User.reset"` name the same method (likewise `Role`, `Session`, and `Installation`), whichever spelling the entry or the `call_method` caller uses. An entry may also name the model by its Ruby constant (`"Artist.purge"` for `class Artist < Parse::Object; parse_class "Musician"; end`), which is compared by its Parse class name too. A qualified entry whose class resolves to no loaded model warns at construction and is matched by its class part as written. Before 5.8.1 an entry was matched against the raw string the caller passed, so `methods: { except: ["_User.reset"] }` could be bypassed by calling it on `"User"`.
 
 The filter **narrows declared methods** — it cannot expose a method that was not declared via the `agent_method` DSL, and it cannot bypass tier checks (`agent_can_call?`) or env-gates (`PARSE_AGENT_ALLOW_WRITE_TOOLS`, `PARSE_AGENT_ALLOW_SCHEMA_OPS`). A filtered-out invocation returns `error_code: :tool_filtered`.
 
@@ -1663,7 +1672,12 @@ class Project < Parse::Object
     # Forward the agent's scope to any internal query — pre-filtering by
     # _wperm so the update only sees rows the agent's scope is allowed
     # to modify, defense-in-depth alongside Parse Server's own ACL.
-    Audit.all(**agent.acl_scope_kwargs).each { |a| a.cancel! } if agent&.acl_scope
+    # acl_scope? is true for any scoped agent, including a session agent whose
+    # token has not resolved yet (acl_scope itself would raise
+    # Parse::Agent::UnresolvedIdentity for that one); acl_scope_kwargs
+    # forwards the identity, and the scoped read fails closed if it cannot
+    # be resolved.
+    Audit.all(**agent.acl_scope_kwargs).each { |a| a.cancel! } if agent&.acl_scope?
     self.archived = true              # property :archived, :boolean
     self.archive_reason = reason      # property :archive_reason, :string
     save
@@ -1714,7 +1728,7 @@ Parse::Agent.new(classes: { only: [Pots] }, strict_class_filter: true)  # per-in
 
 `except:` is never validated — an operator may proactively block a class not yet loaded.
 
-**Sub-agent inheritance: intersect, never widen.** Unlike `tools:` (where a sub-agent's filter overrides the parent's outright), `classes:` is **intersected** with the parent's effective set so a sub-agent can NEVER widen the parent's data reach. A child `only:` that has no overlap with the parent's `only:` raises `ArgumentError` at construction. A child that omits `classes:` inherits the parent's filter verbatim. `except:` sets are unioned (a sub-agent cannot un-deny a class the parent denied). The asymmetry with `tools:` is intentional — class reach is data scope, closer to `permissions:` than to the UX-scoping `tools:` filter.
+**Sub-agent inheritance: intersect, never widen.** Like `tools:` and `methods:`, `classes:` is **intersected** with the parent's effective set so a sub-agent can NEVER widen the parent's data reach. A child `only:` that has no overlap with the parent's `only:` raises `ArgumentError` at construction. A child that omits `classes:` inherits the parent's filter verbatim. `except:` sets are unioned (a sub-agent cannot un-deny a class the parent denied).
 
 **Schema-catalog filtering.** `get_all_schemas` omits classes outside the per-agent allowlist from the catalog response so the LLM doesn't waste a tool call discovering classes it would be refused on.
 
@@ -1793,6 +1807,7 @@ Parse::Agent::Tools.register(
 | `session_token` | Yes (security-critical) | Without it, a session-token parent silently produces a master-key sub-agent — the constructor default is `nil`, which means master-key mode. This was the v4.2 advisor-flagged blocker; do not undo. |
 | `acl_user` (v4.4.0) | Yes (security-critical) | When the parent was constructed with `acl_user:` and the child supplies none of `session_token:` / `acl_user:` / `acl_role:`, the parent's identity inherits verbatim. Inheritance is conditional on the child supplying NO identity at all — explicit overrides on the child resolve normally and then face the subset check below. |
 | `acl_role` (v4.4.0) | Yes (security-critical) | Same rule as `acl_user`. A child that omits identity inherits the parent's role scope; one that supplies its own identity falls through to the subset check. |
+| `master_atlas` | Yes (security-critical) | `nil` inherits the parent's setting and `false` drops it. `true` is accepted only when the parent has it: since 5.8.1 a sub-agent of a parent without `master_atlas` raises `ArgumentError`, because master-key faceting would return every row's buckets and results under the parent's scoped identity. |
 | `tenant_id` | Yes (security-critical) | Without it, a tenant-bound parent produces an unbound sub-agent that escapes `agent_tenant_scope` rules. |
 | `recursion_depth` | Always (decremented) | The parent's budget is authoritative — the explicit `recursion_depth:` kwarg is ignored on inherited construction. |
 
@@ -1802,7 +1817,8 @@ Parse::Agent::Tools.register(
 |-------|---------|
 | `permissions` | The default of `:readonly` means `Parse::Agent.new(parent: write_agent)` produces a `:readonly` sub-agent. A sub-agent is at most as privileged as the parent by tier; this is enforced by a clamp check at construction, not by inheritance. An explicit override is accepted only if `≤ parent.permissions` — `Parse::Agent.new(parent: readonly_parent, permissions: :admin)` raises `ArgumentError`. Pass `permissions: parent.permissions` to maintain parity intentionally. |
 | `client` | The constructor default `:default` resolves to the same client in standard single-app deployments. Explicit passes through. |
-| `tools:` / `methods:` filters | The whole point of constructing a sub-agent is usually to give it a NARROWER surface. Explicit passes through. |
+
+**`tools:` and `methods:` narrow only (5.8.1).** A sub-agent's `tools:` and `methods:` filters can only remove from what its parent allows. A child `tools: { only: }` is intersected with the parent's allowlist and `except:` sets are unioned; a child that omits `tools:` inherits the parent's filter. For `methods:`, the parent's filters stay in force alongside the child's, so a call must pass every one (entries may be bare or `Class.method`, which plain set intersection would match wrongly). A child `only:` list with nothing its parent allows (after the parent's allowlist and `except:` lists apply) raises `ArgumentError` at construction; an explicitly empty `only: []` is the strictest narrowing and is accepted. Before 5.8.1 a child's filter replaced the parent's, so a sub-agent could enable a tool or agent method within its tier that the parent was not given.
 
 **The clamp invariant:** `sub.permissions ≤ parent.permissions` always holds. The default `:readonly` is always safe regardless of parent tier; only explicit overrides hit the clamp check, and overrides that exceed the parent's tier raise at construction. This is the structural guarantee that a `delegate_to_subagent` chain cannot escape the parent's tier through sub-agent construction — the only path to a more-privileged agent is at the MCP factory, where the explicit elevation is auditable.
 
@@ -2785,6 +2801,7 @@ Every tool call dispatched through `Agent#execute` fires the `"parse.agent.tool_
 | `:tools_except` | Array<Symbol> | v4.3.0+ — when the agent was constructed with `tools: { except: [...] }`. |
 | `:methods_only` | Array<String> | v4.3.0+ — when the agent was constructed with `methods: { only: [...] }`. Bare names and `"Class.method"` qualified names mix. |
 | `:methods_except` | Array<String> | v4.3.0+ — when the agent was constructed with `methods: { except: [...] }`. |
+| `:methods_layers` | Array<Hash> | 5.8.1+, sub-agents that inherit at least one `methods:` filter (including a single parent layer when the sub-agent has none of its own). Every `methods:` filter in force, parent layers first and the agent's own last, each `{only:, except:}` with sorted name strings (nil when absent). `:methods_only` / `:methods_except` describe only the agent's own layer. `describe[:methods][:layers]` carries the same list. |
 | `:filters` | Hash<String,Array<String>> | v4.4.0+ — when the agent was constructed with `filters: {...}`. Maps each filtered class name (or `"default"`) to the list of FIELD NAMES the filter constrains. Filter VALUES are intentionally NOT echoed — `filters: { Account => { user_id: "abc123" } }` would otherwise emit the user-identifying value on every audit-log line. Subscribers that need the actual constraint can call `agent.filter_for(class_name)` directly. |
 | `:denial_kind` | Symbol | v4.3.0+, AccessDenied failure path only — one of `:hidden_class` (global `agent_hidden`), `:class_filter` (per-agent `classes:` narrowing), `:field_denied` (outside `agent_fields`), or `:storage_form_field_ref` (referenced `_p_*` pointer-storage column). Lets SOC tooling distinguish operator narrowing from policy-level denials without parsing the message prose. |
 
@@ -3427,7 +3444,7 @@ Parse::Agent.rack_app(logger: Rails.logger) { |env| ... }
 
 **Sub-agent auth-scope inheritance and permissions clamp (v4.2).** When a tool handler constructs a sub-agent with `Parse::Agent.new(parent: agent, ...)`, the sub inherits `session_token` and `tenant_id` from the parent unless explicitly overridden. Without this inheritance, a session-token parent would silently produce a master-key sub-agent — the constructor default `session_token: nil` resolves to master-key mode — escalating privilege through the very kwarg meant to close sub-agent footguns. Explicit overrides still work (`Parse::Agent.new(parent: agent, session_token: nil)` produces a master-key sub if that is genuinely what the handler wants), but the default is fail-safe inheritance. `permissions:` is NOT inherited and defaults to `:readonly`, but the constructor enforces a clamp: an explicit `permissions:` override on a sub-agent is accepted only if `≤ parent.permissions`, otherwise `ArgumentError` is raised at construction. The clamp is the structural guarantee that a delegation chain cannot escape the parent's tier through sub-agent construction. See [Per-Agent Tool Filtering & Sub-Agent Delegation](#per-agent-tool-filtering--sub-agent-delegation-v42) for the full inheritance table.
 
-**Agent-level ACL scope: `session_token:` / `acl_user:` / `acl_role:` (v4.4.0).** `Parse::Agent.new` accepts three mutually-exclusive identity inputs. `session_token:` round-trips Parse Server's `/users/me` at construction (or defers to per-call REST if the server is unreachable). `acl_user:` takes a `Parse::User` or User-pointer and expands the user's role subscription via `Parse::Role.all_for_user` — no token round-trip, the SDK enforces the resulting `_rperm` filter itself. `acl_role:` is service-account-style scoping — no user_id, just the role plus parent-role inheritance. Master-key posture (none of the three supplied) remains the default and still emits the one-time `[Parse::Agent:SECURITY]` banner at construction. Every built-in tool reads `agent.acl_scope_kwargs` (single point of truth) to forward identity into `Parse::MongoDB.aggregate`, `Parse::Query#results_direct`, and `Parse::AtlasSearch.{search,autocomplete}`. Developer-registered tool handlers and `agent_method` bodies can reach `agent.acl_scope`, `agent.acl_permission_strings`, `agent.acl_read_match_stage` (a `_rperm` `$match`), or `agent.acl_write_match_stage` (a `_wperm` `$match`) to apply the agent's identity to their own queries.
+**Agent-level ACL scope: `session_token:` / `acl_user:` / `acl_role:` (v4.4.0).** `Parse::Agent.new` accepts three mutually-exclusive identity inputs. `session_token:` round-trips Parse Server's `/users/me` at construction. If the server is unreachable then, the agent retries on the first tool call that needs its permissions; if that also fails, the call raises `Parse::Agent::UnresolvedIdentity` (reported as `:access_denied`, `kind: :unresolved_identity`) instead of running without the SDK-side check, and further calls within the next few seconds are refused without another lookup (5.8.2). `acl_user:` takes a `Parse::User` or User-pointer and expands the user's role subscription via `Parse::Role.all_for_user`. It makes no token round-trip, and the SDK enforces the resulting `_rperm` filter itself. `acl_role:` is service-account-style scoping: no user_id, just the role plus parent-role inheritance. Master-key posture (none of the three supplied) remains the default and still emits the one-time `[Parse::Agent:SECURITY]` banner at construction. Every built-in tool reads `agent.acl_scope_kwargs` (single point of truth) to forward identity into `Parse::MongoDB.aggregate`, `Parse::Query#results_direct`, and `Parse::AtlasSearch.{search,autocomplete}`. Developer-registered tool handlers and `agent_method` bodies can reach `agent.acl_scope`, `agent.acl_permission_strings`, `agent.acl_read_match_stage` (a `_rperm` `$match`), or `agent.acl_write_match_stage` (a `_wperm` `$match`) to apply the agent's identity to their own queries.
 
 **ACL composition on the mongo-direct aggregate path (v4.4.0).** When `aggregate` routes through `Parse::MongoDB.aggregate` (the default when `Parse::MongoDB.enabled?` is true), the agent layer derives the auth posture from the agent instance and forwards it to ACLScope — session-tokened / acl_user / acl_role agents get the same row-level `_rperm` `$match` injection regardless of identity mode; master-key agents pass `master: true` (the agent's class/field/tenant/canonical-filter gates are the security boundary for that posture). The posture is built in `Parse::Agent#acl_scope_kwargs`, not from tool-call JSON arguments; LLM-supplied `master:`, `session_token:`, `acl_user:`, or `acl_role:` kwargs are silently swallowed by the tool signature's `**_kwargs` catchall and never reach `Parse::MongoDB.aggregate`. An LLM cannot escalate from a scoped posture to master-key by injecting `master: true` into the tool arguments.
 

data/docs/mongodb_direct_guide.md

@@ -287,6 +287,9 @@ raw = Parse::MongoDB.find(
 Convenience wrapper around `db.find`. Accepts `limit:`, `skip:`, `sort:`,
 `projection:`, `hint:`, `max_time_ms:`. When `:limit` is omitted the call applies
 `DEFAULT_FIND_LIMIT = 1000` and warns; pass `limit: 0` to opt out.
+`find` reads raw documents unscoped, so it raises `Parse::ACLScope::ACLRequired`
+inside `Parse.without_master_key`; `Parse::MongoDB.indexes` (metadata only) is
+allowed there.
 
 ### Forcing an index with `hint`
 
@@ -761,6 +764,32 @@ legitimate read stages — but they read from arbitrary collections. Never
 pass attacker-controlled input into a pipeline; build the pipeline in
 trusted code and interpolate only validated values.
 
+#### Regex patterns and the default time limit
+
+Every caller-supplied regex on these paths (`$regex` strings, Ruby
+`Regexp` and BSON regex values, and the `regex` operand of `$regexMatch`,
+`$regexFind`, and `$regexFindAll`) goes through `Parse::RegexSecurity`,
+which parses the pattern and refuses shapes that backtrack heavily on
+PCRE: nested or overlapping repeats such as `(a+)+` or `(a|aa)+`, more
+than three unbounded quantifiers in a row with no separating literal
+(`\d+\d+\d+\d+`), subroutine calls (`\g<1>`), inline comments, and
+extended mode. Escaped literal text, such as the patterns `starts_with`,
+`ends_with`, and `contains` build, always passes the shape check.
+
+A pattern check cannot prove every regex is cheap, so mongo-direct reads
+whose filter or pipeline carries a regex that is not escaped literal text
+also get a server-side `max_time_ms` of
+`Parse::PipelineSecurity.default_regex_max_time_ms` (5000 ms by default)
+when the caller passed none. This covers `Parse::MongoDB.aggregate` and
+`find`, `results_direct`, `count_direct`, Atlas Search, and vector and
+hybrid search. Set the attribute to a different value, or to `nil` to
+turn the default off; an explicit `max_time_ms:` always wins. A query that
+runs past the limit raises `Parse::MongoDB::ExecutionTimeout`.
+
+REST queries are executed by Parse Server, which applies no regex check of
+its own. Set `databaseOptions.maxTimeMS` in the Parse Server configuration
+to bound those.
+
 ### Layer 2: Row-level ACL enforcement (`Parse::ACLScope`) — scoped only
 
 When `Parse::MongoDB.aggregate` is called with `session_token:`,

data/docs/webhooks_guide.md

@@ -210,6 +210,36 @@ run Parse::Webhooks
 See [`examples/webhook_server.rb`](../examples/webhook_server.rb) for a complete,
 runnable setup.
 
+### Authenticating requests, and what `master?` means
+
+Requests are accepted only when `X-Parse-Webhook-Key` matches
+`Parse::Webhooks.key` (`PARSE_SERVER_WEBHOOK_KEY`). With no key configured the
+Rack app refuses every request unless you opt in with
+`Parse::Webhooks.allow_unauthenticated = true` (or
+`PARSE_WEBHOOK_ALLOW_UNAUTHENTICATED=true`), which is meant for local
+development and tests. A signing secret does not replace the key: with no key
+configured, a signed request is still refused unless `allow_unauthenticated`
+is on. When both are configured, the key must match and the signature must
+verify.
+
+`payload.master?` is true only when the body says the master key was used (a
+JSON `true`; Parse Server never sends a string) AND
+the request was authenticated: the webhook key matched, or a configured
+signature (`PARSE_WEBHOOK_SIGNING_SECRET`) verified. On unauthenticated ingress
+any caller can put `"master": true` in the body, so `master?` returns false
+there. Master-only field guards, ACL owner resolution, and handler checks
+built on `master?` therefore treat such a request as a normal client request.
+The Ruby-initiated callback dedup uses `master?` too, so a forged `_RB_`
+request id plus `"master": true` cannot make a request skip model callbacks
+(including a `before_save` that would reject it). `payload.claimed_master?`
+returns the body's raw claim and `payload.authenticated?` reports whether the
+request was authenticated; both are for diagnostics only.
+
+The trade-off: on unauthenticated ingress, a save made by the SDK itself is
+not recognized as Ruby-initiated, so its model callbacks can run twice (once
+in process, once through the webhook). Configure a webhook key or a signing
+secret to keep the dedup.
+
 ## Auditing trigger coverage
 
 The wiring above has three independent moving parts, and a callback runs
@@ -284,13 +314,65 @@ database untouched. When the handler changed fields, the reply is the client's
 full write with your changes layered on top: operators on fields you did not
 touch are passed through as operators, fields the model does not declare (and
 `_User` signup fields such as `password` and `authData`) are kept, and a field
-you set back to its stored value is dropped from the write. Two limits come
-from what Parse Server sends the webhook: a field you rewrite is written as an
-absolute value, and an operator on a dotted sub-key (`"meta.count"`) arrives
-only as its resulting sub-document and is written back that way. Edits made
-in place on `parse_object` count even if the handler returns `true`. On a
-create, returning `parse_object` also writes the model's declared defaults
-(including its default ACL) for fields the client did not send.
+you set back to its stored value is dropped from the write. A field you
+rewrite is written as an absolute value. Edits made in place on `parse_object`
+count even if the handler returns `true`.
+
+An operator on a dotted sub-key (`"meta.count"`) arrives only as its resulting
+sub-document, so on an update the SDK writes back just the sub-keys that
+changed, as dotted paths, and a removed sub-key as a `Delete`. The split is one
+level deep: a changed sub-key is written whole at `field.sub`, nested objects
+included, because Parse Server rebuilds the afterSave object from a dotted key
+only one level deep. Concurrent writes to other sub-keys of the field survive.
+Some limits remain:
+
+- Two concurrent writes inside the same sub-key can still overwrite each
+  other, including two operators on deeper paths under it
+  (`meta.count.value` and `meta.count.other`).
+- An array is written whole, so a concurrent `Add` to an array inside a
+  sub-document is lost.
+- When a changed sub-key would carry a typed value (a Date, Bytes, Pointer, or
+  other `__type` value), the whole field is written instead, because Parse
+  Server stores a dotted typed value without converting it. Unchanged typed
+  values and deletes do not trigger this.
+- A client that replaces a whole sub-document gets a merge: the changed
+  sub-keys are written and the sub-keys it knew about and removed are
+  deleted, so a sub-key another request added in the meantime survives.
+- Parse Server reports the reply's dotted keys back to the client in the save
+  response. The JavaScript SDK applies them; other clients may need to fetch
+  the object to see the merged value.
+- A dotted key in a Hash the handler returns (`{ "meta.y" => 5 }`) is folded
+  into the parent path the reply writes whole. A key deeper than one level
+  (`"meta.count.value"`) is folded into a `meta.count` write built from the
+  pending object, and on a create every dotted key folds into its whole
+  field. An operator folded this way (`{"__op" => "Increment"}`, `Add`,
+  `AddUnique`, `Remove`, `Delete`) is applied to the value it replaces; an
+  operator that cannot be applied there, or two of your own keys that
+  conflict (`"meta.a" => 5` with `"meta.a.b" => 6`), fails the save with an
+  error. Hash keys may use Ruby names (`acl:`); they are mapped to the
+  stored field names.
+
+On a create, returning `parse_object` also writes the model's declared
+defaults for fields the client did not send, including its ACL policy. Parse
+Server stores a create without an `ACL` as public read and write, so the reply
+always carries the ACL your policy resolves, exactly as an SDK-side create
+would. Owner-based policies (`:owner_else_private`, the default, as well as
+`:owner_else_public` and `:owner_but_public_read`) take the owner from the
+declared `owner:` field and, when that is empty, from the user who made the
+request, so a signed-in client owns what it creates. A request without a user
+gets the policy's fallback (master-key only under `:owner_else_private`), and so
+does a master-key request. A `_User` class declared with `owner: :self` is
+owned by the new user, never by the requester: the reply carries the policy's
+ACL without an owner entry and Parse Server adds the new user's own read and
+write. An ACL the client sent is kept, and an ACL the handler sets always
+wins, whether through `acl=` or mass assignment. A `guard :acl, :master_only`
+revert on a create returns the ACL to the class policy rather than to `{}`.
+Built-in classes such as `_User` that have no policy of their own keep Parse
+Server's defaults. A handler that returns `true`, `nil`, or a Hash keeps the client's
+write as sent, so a create without an ACL stays public; return
+`parse_object` to apply the policy. An ACL the handler assigns on
+`parse_object` (`parse_object.acl = Parse::ACL.new`) is written whatever the
+handler returns, unless a returned Hash sets `ACL` itself.
 
 `after_destroy` callbacks run in the `after_delete` handler (once per delivery,
 skipped for deletes the SDK itself made, whose callbacks already ran locally).
@@ -434,8 +516,11 @@ master key). It has already run the model's `before_save` / `after_save` /
 The intent is to keep trigger logic local when possible and run it exactly once.
 Note that any logic in the **webhook block itself** still runs; only the
 duplicate ActiveModel callback pass is skipped. A spoofed `_RB_` marker without
-the master key does not get this treatment — the callbacks run in the webhook as
-usual.
+the master key does not get this treatment, and neither does a claimed master
+key on an unauthenticated request (no webhook key match and no verified
+signature): the callbacks run in the webhook as usual. On unauthenticated
+ingress this means SDK-initiated saves run their callbacks twice; configure a
+webhook key or signing secret to keep the dedup.
 
 ### 2. Server-initiated replay / freshness protection (inbound)