parse-stack-next 5.8.0 → 5.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca6cbc923754826337ad1abf67ad900d15ac483cef4d03536862923491eaf64c
-  data.tar.gz: 3c5c10805ec33190f755e8a745c4b6cbac2fd2bd458f1032b57e125e86ed6e73
+  metadata.gz: de8e9c2d24346754146f36a8c24b272840456010e08bf86f71b11d38741abad8
+  data.tar.gz: 83df07a458c9e00cae15f63fe12d4e8c19bc6913f60b297e1fa402985b2073ce
 SHA512:
-  metadata.gz: a34e92d57d8cfbd3ba87bbe21baad8995a7dd1f3aba09a980ab3ed364ab961e5f8934a6bd73f4c097895cdfc5a427e5e4b3c01e0405c6647731384bbb9fd2747
-  data.tar.gz: f7898ed1327fb0f316bda290f36b1cf8a4ab74d4d510243b276e408dd7d7d95e1e97e96e13d5c784b39c83c262574b57c34ce8b4d15983603e19194d477883fe
+  metadata.gz: ead735d8d48a495293b810f2b6100327869ae68051d9e1aaee87b43d51aeb51b1323e6f29a9b823a40ec0ac15b52bfc91eb838009524239bd7f1f42a63d7e02d
+  data.tar.gz: 0666b77620a76d2b19a81a5a43f3a9cd61f94661568c269ac07e612c71ff25642c4759d93f0e0b7d7370bb3930447f1fa39ed3eb986fa9bf73a63a072009cbb8

data/CHANGELOG.md

@@ -1,5 +1,323 @@
 ## parse-stack-next Changelog
 
+### 5.8.1
+
+A correctness release for webhooks, sessions, associations, queries, search,
+and agent policies. No new defaults and no API changes; every corrected
+outcome is listed under Behavior Notes.
+
+#### Webhooks
+
+- **FIXED**: A client create through a `before_save` webhook whose handler
+  returns `parse_object` now gets the ACL its class policy resolves, exactly
+  as an SDK-side create would. Owner-based policies (`:owner_else_private`,
+  the default, plus `:owner_else_public` and `:owner_but_public_read`) take the
+  owner from the declared `owner:` field, or from the requesting user when that
+  field is empty. Before, a signed-in client got the policy's no-owner
+  fallback (`{}` under `:owner_else_private`) and could not read its own
+  record. A request without a user, or a master-key request, gets the policy
+  fallback. A `_User` class declared with `owner: :self` is owned by the new
+  user, never the requester. An ACL the client sent is kept, and an ACL the
+  handler sets always wins (through `acl=` or mass assignment), even when it
+  equals the class default. A `guard :acl, :master_only` revert on a create
+  returns the ACL to the class policy instead of `{}`. A handler-assigned ACL
+  is written whatever the handler returns (`parse_object`, `true`, `nil`, or
+  a Hash that does not set `ACL` itself).
+- **FIXED**: When a `before_save` handler changes a record, a sub-document the
+  client changed is written back as one-level dotted paths (`"meta.count":
+  {...}`) instead of the whole field, so concurrent writes to other sub-keys
+  survive. A removed sub-key is written as a `Delete`. Dotted keys in a
+  returned Hash are folded into the field or `field.sub` write they belong to,
+  with operators (`Increment`, `Add`, `AddUnique`, `Remove`, `Delete`) applied
+  rather than stored. Hash keys may use Ruby names.
+
+#### Sessions and master-key scope
+
+- **FIXED**: Deleting `Parse::Session` or `Parse::User` objects, one at a time
+  or with a batch `Array#destroy`, drops their identity-cache entries when the
+  delete succeeds or reports the row already gone. A denied delete leaves the
+  cache alone. A session that does not carry its token or owner (built from
+  its objectId alone, fetched without the master key, or fetched with `keys:`
+  leaving them out) has them looked up first, in one query per batch: with the
+  master key when the client has one, otherwise with the delete's `session:`.
+  A lookup that finds no row leaves nothing to forget; only a lookup that
+  fails resets the client's identity cache, at most once every 5 seconds per
+  client. When the lookup finds no row, the delete uses the owner recorded
+  when a `_Session` query or `Parse::Session.session` last fetched that
+  session through the same client (only the user id, never the token, in a
+  store separate from the identity plane,
+  `client.authorization.session_owner_cache`). Without one, a batch delete
+  that applied or reported the row gone falls back to the rate-limited reset;
+  a denied delete never resets, and a single `destroy` never resets. The
+  looked-up token is used only for the delete, is never kept on the object,
+  and never enters the response cache. A token resolution in flight when an
+  invalidation lands, in this process or, on the Redis identity plane, in any
+  other, does not cache its answer: the resolver checks a shared invalidation
+  marker before and after writing and evicts its own write when the marker
+  moved.
+- **FIXED**: `Parse::User#signup!`, signup on save, and `upgrade_anonymous!`
+  store `created_at` / `updated_at` as `Parse::Date` values. Reading
+  `updated_at` on a newly signed-up user no longer marks it dirty.
+- **FIXED**: Inside `Parse.without_master_key`, an explicit `master: true`
+  passed to `Parse::MongoDB.aggregate`, `Parse::ACLScope`, `Parse::Query`
+  direct reads, vector and hybrid search, Atlas Search, or agent tools for
+  master-key agents no longer runs as master. The call runs in the public
+  scope, as the REST request does once the block strips its master key, and
+  the `parse.mongodb.aggregate` notification reports `master_dropped: true`.
+  The SDK's own metadata reads keep the master key without lifting the block:
+  the class schema and role graph read to enforce a scope, index statistics,
+  and the Atlas Search index listing. Before, a schema read refused inside the
+  block was cached and denied every scoped mongo-direct read of that class,
+  for all callers, for 5 seconds. `Parse::AtlasSearch.faceted_search` raises
+  `FacetedSearchNotACLSafe` inside the block, because its bucket counts are
+  not ACL-filtered. The metadata marker rides only on the outgoing request
+  copy, never on `response.request` or an error's request. A schema read that
+  fails inside the block is retried at most every 2 seconds there. A LiveQuery
+  admin client that first connected inside the block keeps withholding its
+  master key on every reconnect until `allow_master_key_connection!`.
+
+#### Agent policies
+
+- **FIXED**: A sub-agent's `tools:` and `methods:` filters now only narrow its
+  parent's, as `classes:` already did. A child `tools: { only: }` is
+  intersected with the parent's allowlist and `except:` sets are unioned; for
+  `methods:` the parent's filters stay in force alongside the child's. Before,
+  the 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. A child
+  `only:` list with nothing its parent allows raises `ArgumentError` at
+  construction.
+- **FIXED**: A sub-agent built with `parent:` uses its parent's approval gate,
+  read at call time, unless given its own. Before, it fell back to
+  `NullGate`, so a sub-agent built inside an MCP `tools/call` ran tools in
+  `require_approval_for` tiers without approval.
+- **FIXED**: Qualified `methods:` entries compare the class by its Parse class
+  name, so `"User.x"` and `"_User.x"` (and the `Role`, `Session`, and
+  `Installation` aliases) match whichever spelling the entry or the
+  `call_method` caller uses. Before, `methods: { except: ["_User.x"] }` could
+  be bypassed by calling the method on `"User"`.
+- **FIXED**: A sub-agent can no longer turn on `master_atlas` when its parent
+  does not have it. `Parse::Agent.new(parent: scoped_parent, master_atlas:
+  true)` raises `ArgumentError`; before, the child's `atlas_faceted_search` ran
+  with master-key semantics and returned every row under the parent's scoped
+  identity. Omitting `master_atlas` still inherits, and `false` still drops
+  it.
+- **FIXED**: The MCP dispatcher snapshots and restores an agent's own approval
+  gate, so driving a sub-agent through `tools/call` no longer pins its
+  parent's gate onto it. Assigning `approval_gate = nil` makes a sub-agent use
+  its parent's gate again.
+- **FIXED**: Qualified `methods:` entries may name a model by its Ruby
+  constant (`"Artist.purge"` for a class whose `parse_class` is `"Musician"`)
+  and are compared by Parse class name, so such an `except:` entry is no
+  longer bypassed through the Parse class name. An entry whose class resolves
+  to no loaded model warns at construction.
+- **IMPROVED**: The `parse.agent.tool_call` audit payload adds
+  `methods_layers` whenever a sub-agent inherits a `methods:` filter
+  (including a single parent layer), and `describe[:methods][:layers]` lists
+  every `methods:` filter in force, parent first.
+
+#### Associations
+
+- **FIXED**: `add!`, `add_unique!`, and `remove!` on a
+  `has_many through: :array` collection take the array Parse Server returns,
+  as plain array properties already did. A stale local copy is corrected,
+  objects already fetched locally are kept, and the field is not marked
+  changed. The array is adopted only when every entry is a pointer to the
+  declared class; otherwise the operation is applied locally.
+- **FIXED**: Saving a relation collection on its own (`owner.likes.save`)
+  sends the staged additions and removals and returns whether they were
+  applied. Before, it silently sent nothing.
+- **FIXED**: `Parse::Object#clear_changes!` (also called by `reload!`) drops
+  a relation's staged additions and removals and clears array collection
+  dirty state. Before, discarded relation changes were sent with the next
+  change to that relation. A fetch (`fetch!`, partial fetch, autofetch, with
+  or without `preserve_changes:`) keeps a relation's staged additions and
+  removals and leaves the relation marked changed, including when the response
+  carries the relation's descriptor, so the next save sends them.
+  `rollback!` drops a relation's staged additions and removals too, including
+  after a fetch.
+- **IMPROVED**: `RelationCollectionProxy#save` accepts `session:` to send the
+  staged operations as a given user (`nil` for no session token). Relation
+  writes on an owner whose objectId was assigned client-side during a create
+  are staged rather than sent until the create returns.
+- **FIXED**: Atomic relation operations (`add!` / `remove!` on a
+  `through: :relation` collection) write to the relation's Parse column when
+  its name differs from the Ruby name (`has_many :liked_items` maps to
+  `likedItems`, or a relation declared with `field:`). Before, they targeted
+  the Ruby name.
+
+#### Queries
+
+- **FIXED**: An OR whose branch has no constraints now matches every row.
+  Previously `query | Model.query` and `Parse::Query.or(query, Model.query)`
+  dropped that branch and returned only the other side. An empty receiver of
+  `|` still starts a new OR, as `or_where` does, so
+  `[q1, q2].reduce(Model.query, :|)` builds `q1 OR q2`.
+- **FIXED**: `Model.query(:or => [{...}, {...}])` builds a `$or` group ANDed
+  with the query's other constraints, instead of a constraint on a literal
+  field named `or`. Branches can be constraint hashes, `Parse::Query` objects
+  of the same class, or arrays of constraints.
+- **FIXED**: A constraint that needs the aggregation pipeline or mongo-direct
+  (`readable_by`, `:ACL.readable_by`, `:field.array_size`, the mongo-direct geo
+  operators) raises `ArgumentError` inside an OR (`:or`, `or_where`, `|`,
+  `Parse::Query.or`). Before, the branch was emitted as `{}` and matched every
+  row, or lost part of its conditions, including in push targeting, which
+  could reach every installation.
+- **FIXED**: `Parse::Query#clone`, `|`, `or_where`, `Parse::Query.or`, `:or`
+  branches (including Hash branches with `session:` / `use_master_key:` keys
+  or nested scoped queries), and subqueries (`$inQuery`, `$notInQuery`,
+  `$select`, `$dontSelect`) keep the query's authority and application:
+  session token, a session-bound client from `Parse::Client#become`, scoped
+  user or role, master-key flag, read preference, and the Parse application
+  the query targets. Queries combined this way must run under the same
+  authority against the same application. An unscoped query takes the
+  other's authority, and different authorities or applications raise
+  `ArgumentError`. Before, a session combined with `scope_to_user` ran as the
+  scoped user, a `become`-client query composed into an OR ran as the master
+  key, a scoped subquery ran under the outer query's master key, and a clone
+  could send one application's session token to the default application.
+  Changing the authority or client of a combined query raises and leaves the
+  query unchanged. A combined query re-checks its authority before it runs,
+  and explicit auth passed to `results_direct`, `count_direct`,
+  `distinct_direct`, or `atlas_search` must match it.
+- **FIXED**: LiveQuery subscriptions and push targeting refuse constraints that
+  only the aggregation pipeline or mongo-direct can run (`array_size`,
+  `set_equals`, `not_empty`, `elem_match`, `readable_by`, mongo-direct geo
+  operators). Before, those constraints were dropped and the subscription or
+  push reached a wider audience. A subquery with such a constraint is also
+  refused, where it used to match every row. `Parse::Query#subscribe` and
+  `client.subscribe(query)` run under the query's own session or `become`
+  client, and such a subscription is refused with `ArgumentError` when the
+  LiveQuery client targets a different Parse application id than the query,
+  so one application's session token is never sent to another application's
+  LiveQuery server.
+- **FIXED**: A field repeated in `order` is sent once, at its first position
+  with the last direction given, matching what MongoDB applies on direct
+  reads. String forms such as `"-title"` are parsed as descending, so they
+  deduplicate too, and the direct `$sort` stage sorts on the real field.
+  `order("title,-plays")` is parsed as two fields.
+- **FIXED**: A bare objectId compared to a declared pointer field
+  (`Song.query(:artist => "abc123")`, `:artist.ne`, `:artist.in`) now matches
+  on REST, in `Parse::Push` targeting, and in LiveQuery subscriptions from
+  `Parse::Query#subscribe`, `Model.subscribe`, and `client.subscribe(query)`.
+  Equality and `$in` used to return no rows and `$ne` every row, while direct
+  and aggregate reads already matched. The new
+  `Parse::Query#compile_rest_where` returns the where clause in that form.
+
+#### Search
+
+- **FIXED**: Atlas Search (`Parse::AtlasSearch.search`, `search_with_stage`,
+  `autocomplete`, `Parse::Query#atlas_search`) and native hybrid search apply
+  the CLP `pointerFields` / `readUserFields` ownership constraint before the
+  page is cut. For native hybrid, the lexical input filters before its
+  per-input `$limit`, and the fused result is filtered again before the final
+  `$limit`. Rows used to be filtered after the page was cut, so when the
+  top-ranked hits belonged to other users a scoped caller got a short or empty
+  page. Inaccessible rows are still never returned.
+- **IMPROVED**: `Parse::VectorSearch.search` and native hybrid search enforce
+  the `pointerFields` ownership constraint server-side across the whole
+  candidate window. When every owner field is declared as a scalar pointer
+  (`belongs_to`) and its storage path (`_p_<field>`) is a `type: "filter"`
+  field of the vectorSearch index, the constraint also goes
+  into `$vectorSearch.filter`, so other users' rows no longer use up the
+  candidate window. The prefilter is used only while the index is READY and
+  serving its latest definition. If Atlas refuses it (for example mid-rebuild),
+  the search reruns once without it and skips it for the index cache TTL. A
+  failed index lookup is also remembered for that TTL.
+
+- **FIXED**: A `$vectorSearch` refusal caused by the caller's own
+  `vector_filter` on an unindexed path no longer switches off the owner
+  prefilter for every caller on that index or clears the index cache; only a
+  refusal naming an owner `_p_<field>` path does. Native hybrid search uses
+  `Parse::VectorSearch.default_index` when the vector branch names no index.
+
+#### Documentation
+
+- **FIXED**: README and query YARD examples use `:field.pointer_id` and
+  `:field.array_size`, the names the DSL has used since 5.8.0.
+
+#### Behavior Notes
+
+- An OR that includes an unconstrained branch now returns every row. The one
+  exception is an empty receiver of `|`, which starts the OR. Code that passed
+  an empty query for "no filter" should leave that branch out. `:or => []`
+  matches no rows.
+- A pipeline-only constraint inside an OR now raises `ArgumentError`. Apply it
+  outside the OR, or run the branches as separate queries.
+- Combining queries that run under different authorities or against
+  different Parse applications now raises `ArgumentError`. That covers OR
+  composition, `:or` Hash branches, and subqueries, and includes different
+  session tokens, a session against `scope_to_user` / `scope_to_role` / the
+  master key, and different scoped users or roles. Setting a new session
+  token, master-key flag, scope, or client on a query that took its authority
+  from another query also raises, as does passing different explicit auth to
+  a direct or Atlas terminal. Query-shaping options (`limit`, `order`, `keys`,
+  `skip`, `include`) inside an `:or` branch raise.
+- LiveQuery subscriptions, push targeting, and subqueries with pipeline-only
+  constraints raise `ArgumentError`. Subscribing to a `scope_to_user` /
+  `scope_to_role` query, or passing a `session_token:` that differs from the
+  query's session, raises.
+- REST queries, LiveQuery subscriptions, and push targeting that compare a
+  bare objectId to a declared pointer field now return the matching rows.
+  Undeclared fields are unchanged. If a model declares `belongs_to` for a
+  field whose server column holds a plain String, a bare string compared to
+  that field is now sent as a Pointer and stops matching those values;
+  declare such a field as a `:string` property instead.
+- Code that relied on `master: true` keeping master authority inside
+  `Parse.without_master_key` should wrap that call in `Parse.with_master_key`.
+  A dropped `master: true` raises `ACLRequired` under either
+  `Parse::ACLScope.require_session_token` or
+  `Parse::AtlasSearch.require_session_token`, with a message naming the block,
+  and no longer emits the no-ACL banner. The role-graph helpers
+  (`users_in_role_subtree` and related) raise `ACLRequired` for
+  `master: true` inside the block; pass `as:` instead.
+- A LiveQuery connection that already connected with the master key outside
+  `Parse.without_master_key` stays elevated for subscriptions made inside the
+  block, because Parse Server authorizes per connection; the SDK warns.
+- `Parse.without_master_key` guards against accidental master-key use and is
+  not an isolation boundary.
+- `Parse::Role.all_for_user` and `Parse::Role#all_parent_role_names` without
+  `master:` or `as:` return the full role closure inside
+  `Parse.without_master_key`, because the role graph is read as SDK metadata.
+- `Parse::Session._preload_identity_for_destroy!` and the
+  `_after_batch_destroy` hooks are now private.
+- A session deleted elsewhere whose owner this process never recorded keeps
+  resolving until the next rate-limited reset or `identity_cache_ttl`.
+- A custom identity plane gets the cross-process revocation-race guarantee by
+  implementing `invalidation_nonce` and `bump_invalidation_nonce`, as the
+  built-in Redis plane does. One with generation counters only is covered for
+  single-token and per-user invalidations, but a lookup racing another
+  process's full reset is bounded by `identity_cache_ttl` when the plane's
+  `clear` also deletes its counters.
+- A sub-agent's `tools:` or `methods:` `only:` list that leaves nothing once
+  the parent's `only:` and `except:` lists apply now raises `ArgumentError`.
+  An explicitly empty `only: []` is accepted. A sub-agent passing
+  `master_atlas: true` under a parent without it raises `ArgumentError`.
+- Parse Server sends a `before_save` webhook only the resulting value of a
+  dotted operator. When the handler changes the record, the SDK writes back
+  changed sub-keys one level deep and deletes removed ones by path. Two
+  concurrent writes inside the same sub-key (including deeper paths under it)
+  can still overwrite each other, an array is written whole, and a changed
+  sub-key carrying a typed value (Date, Bytes, Pointer) makes the whole field
+  be written. A client's whole replace of a sub-document becomes a merge. The
+  save response reports the dotted keys; the JavaScript SDK applies them, and
+  other clients may need a fetch. A handler operator that cannot be folded,
+  or two conflicting dotted keys from the handler, fail the save with an
+  error.
+- A `before_save` handler that returns `true`, `nil`, or a Hash keeps the
+  client's write as sent, so a client create without an ACL through such a
+  handler is stored public read and write, as before, unless the handler
+  assigns an ACL on `parse_object`.
+- Saving a relation collection on its own sends removals and additions as two
+  requests. If the second fails, the first stays applied and the unsent
+  operations stay staged.
+- Owner fields stored as arrays of pointers, undeclared, or not filter-indexed
+  get no `$vectorSearch` prefilter. Vector search then fills results only from
+  its existing candidate window.
+- A custom identity cache with neither `invalidate_value` nor generation
+  support (`generation`, `generation_current?`, `bump_generation`) only
+  expires a user's tokens at `identity_cache_ttl` after a password change,
+  account deletion, `logout_all!`, or a batch destroy of sessions.
+
 ### 5.8.0
 
 #### Breaking Changes

data/README.md

@@ -3873,8 +3873,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 +3976,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 +4033,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 +4213,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 +4221,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 +4260,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 +5813,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 +6101,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

@@ -358,6 +358,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

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`.
 
@@ -1714,7 +1723,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 +1802,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 +1812,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 +2796,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. |