parse-stack-next 5.2.0 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25238eea832d32b8c536522ec1c43d087b3db8e996b13d39430c2edfd74481ee
-  data.tar.gz: 806f28241cfbfe7e77fa230bd2e6b2b4aa071b89b7dda828f52d0b5182a7122c
+  metadata.gz: 90a966c230e0a0e2e6fd814170726e3af713dae06c0341a00cd7581eecbe53ee
+  data.tar.gz: b171ed432c7ea7806ec07653b47122bd6102a16046c980d915fe45f98ffbca32
 SHA512:
-  metadata.gz: b85adcba96ac6023989bf42e8676eee9bb22b4ef0cb02073cc7ed0b79078c3edd88a84ff6f0b6c6f15eda214ba6a9c3165d35c7c250ef1ecfcd0471f58c3929c
-  data.tar.gz: 9646a8b0f4bcd679a373d8a3ba189f0f160a7227280690b2ca165987b535f0c0ac6972dcf04d053ba441b732f80462698d7e1e08365c4419368aeea4481117c6
+  metadata.gz: 510f3f2deb860cedc73f11455fb5d4789c327923abebad4e26b223ae9c385374ffa23bc9564561e7d4dddb31b0c1a015b7e7222dacd7c0b18bdb01199580d7a0
+  data.tar.gz: cd0fb4c706b3c33f12059c7431cf75abd792cbd5ba8b193dd43256aaa70c8fcdd3f86e10b3ad8ffb25c8e9ccc3f985a61bcaa8b49d24badf6f8358cec2b16f3d

data/.bundle/config

@@ -1,4 +1,5 @@
 ---
 BUNDLE_FORCE_RUBY_PLATFORM: "true"
+BUNDLE_FROZEN: "false"
 BUNDLE_PATH: "/home/runner/work/parse-stack-next/parse-stack-next/vendor/bundle"
 BUNDLE_DEPLOYMENT: "true"

data/CHANGELOG.md

@@ -1,5 +1,245 @@
 ## parse-stack-next Changelog
 
+### 5.3.0
+
+#### Run webhook handlers as the calling user
+
+Parse Server includes the caller's live session token (`user.sessionToken`) in
+every trigger webhook fired by a logged-in user. A handler can now opt in to
+acting on the server *as that user* — with full ACL, CLP, and `protectedFields`
+enforcement — instead of reaching for the application master key.
+
+- **NEW**: `Parse::Webhooks::Payload#session_token` exposes the caller's session
+  token, captured from the incoming payload. It is `nil` for a master-key
+  request (which carries no user). The token is captured before the payload's
+  credential scrubbing runs, so it is still removed from `payload.user` /
+  `payload.object` and never appears in `payload.as_json` or the request log.
+- **NEW**: `Parse::Webhooks::Payload#user_agent` returns a non-master
+  `Parse::Agent` bound to the caller's session token, so it runs in client mode
+  and every query is authorized as the user. Returns `nil` when there is no
+  token.
+- **NEW**: `Parse::Webhooks::Payload#user_client` returns a non-master
+  `Parse::Client` that binds the caller's session token, so even raw REST calls
+  through it are authorized as the user with no further ceremony. Returns `nil`
+  when there is no token.
+- **NEW**: `Parse::Client.new` accepts a `session_token:` option that binds a
+  token to the client. It is applied as the lowest-priority auth fallback on
+  every request (explicit per-call `session_token:` and `Parse.with_session`
+  still take precedence, and an explicit `use_master_key: true` skips it).
+  Pair it with `master_key: nil` to build a user-scoped client.
+- **NEW**: `Parse::Client#become(session_token)` returns a new non-master client
+  that mirrors the receiver's connection settings (`server_url`/`app_id`/
+  `api_key`) but binds the given token — the primitive behind `payload.user_client`
+  and `Parse::User#session_client`. `Parse::Client#anonymous` returns the same
+  shape with no token (unauthenticated REST) to drop a bound identity.
+- **NEW**: `Parse::User#session_client` returns a non-master `Parse::Client`
+  bound to a logged-in user's session token — the client-side counterpart of
+  `payload.user_client` (e.g. `Parse::User.login(u, p).session_client`).
+- **NEW**: `Parse::Client#with_session { ... }` runs a block with the client's
+  bound session token active as the ambient session, so REST-routed operations
+  (`find`/`get`/`count`/`save`) inside it are authorized as the user without
+  passing `session_token:` per call (the client-receiver flavor of
+  `Parse.with_session` / `Parse::User#with_session`). Mongo-direct queries
+  (`results_direct`, `aggregate`, Atlas search) are unaffected and still require
+  explicit per-query scoping.
+- **NEW**: `rake client:console` opens an interactive console whose default
+  client is a non-master client bound to a user (session token, login, or
+  anonymous), so every query in the session runs with that user's ACL / CLP /
+  `protectedFields` rather than the master key.
+- **FIXED**: `Parse::Client#inspect` and `Parse::Webhooks::Payload#inspect` no
+  longer print the master key or session token (and, for the payload, the
+  pre-scrub raw credentials) in cleartext — they are redacted, so an error
+  reporter or stray `inspect` cannot leak them.
+- **FIXED**: a whitespace-only `Parse::Client` `session_token:` is now treated
+  as no token, so it can never silently fall through to the master key.
+
+#### Pluralized class-name aliases
+
+Referencing the plural form of a model constant now resolves to that class, so
+the plural reads naturally as a query entry point — `Posts.where(...).count`
+works for a class `Post`.
+
+- **NEW**: The plural alias is created lazily on first reference and is the
+  *same class object* as the singular (`Posts.equal?(Post)` is `true`), so every
+  class method works through it (`query`/`where`, `count`, `find`, `all`, and any
+  `scope`) and `Posts.parse_class` still returns `"Post"`. Because it is the same
+  class, it adds no `Parse::Object.descendants` entry and never registers a
+  separate Parse schema class.
+- **NEW**: `pluralized_alias!` class macro for explicit opt-in — use it for a
+  custom plural, a class whose name ends in `s`, or a namespaced model (the alias
+  is defined on the enclosing module). It ignores the global flag and raises
+  `ArgumentError` rather than clobbering an existing unrelated constant.
+- **NEW**: `Parse.pluralized_aliases` configuration (default `true`; opt out with
+  `Parse.pluralized_aliases = false` or `PARSE_PLURALIZED_ALIASES=false`).
+- **CHANGED**: The automatic path is conservative — a class whose name already
+  ends in `s` is skipped, and a plural that does not singularize to a known
+  `Parse::Object` subclass falls through to a normal `NameError`.
+
+#### Pointer associations declared with `property … as:` — BREAKING: now serialize as Pointers
+
+Declaring a pointer with `property` instead of `belongs_to` used to fail
+silently: the `as:` option was dropped and the field became a plain `:string`
+column, so an assigned object was stored as a String and never serialized as a
+Parse pointer. `property … as:` now resolves to the same pointer association as
+`belongs_to`.
+
+- **BREAKING**: a field declared with `property … as:` now serializes as a
+  Pointer (`{__type: "Pointer", …}`) instead of a String. If a deployed app
+  previously used `property … as:` and saved records, Parse Server pinned that
+  column as `String` on first write, and a Pointer write against it is rejected
+  with error 111 (schema type mismatch). Drop or migrate that column to a
+  Pointer type before deploying. Apps that never used `property … as:` are
+  unaffected — the option was a silent no-op, so no working pointer behavior
+  depended on it.
+- **FIXED**: `property <name>, as: <class>` and `property <name>, :pointer` now
+  declare a pointer association identical to the equivalent `belongs_to` — same
+  `:pointer` field type, remote column, target-class reference, getter/setter,
+  dirty tracking, and `{__type: "Pointer", …}` wire form. Previously `as:` was
+  ignored and the field defaulted to `:string`, with no warning.
+- **NEW**: `belongs_to` (and the delegating `property … as:`) raise an
+  `ArgumentError` at declaration time when `as:` names a scalar data type such
+  as `as: :string` — a scalar cannot be a pointer target. The message points to
+  the intended `property <name>, :<type>` form. The guard fires only on an
+  explicit `as:`, so existing `belongs_to :field` declarations are unaffected.
+- **NEW**: `Parse.validate_associations!` verifies that every `belongs_to` /
+  `property … as:` pointer target and every `has_many` target — relation-,
+  array-, and query-backed — resolves to a known Parse class, reporting any
+  unresolved target as a `Class#field -> "Target"` offender. The query- and
+  array-backed `has_many` targets are the bucket where an `as:` typo otherwise
+  stays latent until the association is first traversed. Forward references are
+  legal at
+  declaration time and indistinguishable from typos there, so this cross-class
+  check is meant to run once after all models load (boot, CI, or a rake task).
+- **IMPROVED**: `belongs_to` now stores `_description:` and `_enum:` agent
+  metadata, which previously only `property` retained. A documented pointer
+  association keeps its semantic description, including when declared through
+  `property … as:`.
+
+#### afterSave create reports changed fields; file equality is force_ssl-consistent
+
+A trigger handler that keys off dirty tracking (`*_changed?` / `changes`) now
+sees every field an object was created with on an `afterSave` create, symmetric
+with the existing `afterSave` update behavior, and two `Parse::File` values that
+point at the same location compare equal regardless of `force_ssl`.
+
+- **NEW**: On an `afterSave` trigger for a newly created object (no prior
+  persisted state), the built `Parse::Object` now marks every populated data
+  property as changed, so a handler can use `*_changed?` / `changes` / `changed`
+  uniformly across create and update. Previously the create object
+  was pristine, so `*_changed?` returned `false` for every field and a handler
+  that builds a payload from changed fields would see nothing on creates. A
+  property whose create value equals its declared `default:` (e.g.
+  `status: "draft"`, `count: 0`, `archived: false`) is correctly reported as
+  changed. System fields (`createdAt` / `updatedAt` / `ACL` / `objectId`) stay
+  clean — they are not reported as changed — and object readability, `new?`, and
+  `existed?` are unchanged. Credential and row-permission fields remain filtered
+  from the built object. The `afterSave` update path is unchanged.
+- **CHANGED**: As a result of the above, model `after_save` / `after_create`
+  callbacks fired through the webhook dispatcher now observe an `afterSave`-create
+  object whose data fields are dirty (rather than pristine). A handler that
+  branched on dirty state for a created object should review that expectation;
+  the values themselves are unchanged.
+- **FIXED**: `Parse::File#==` now compares both files through the canonical
+  `url` reader rather than the raw stored URL on one side, so the comparison is
+  symmetric (`a == b` matches `b == a`) and consistent when
+  `Parse::File.force_ssl` coerces a stored `http://` URL to `https://`. Two
+  files at the same location previously read as unequal under `force_ssl`, which
+  could spuriously mark a file property as changed during dirty tracking.
+  Signed-URL query parameters are still stripped before comparison, so a
+  re-signed URL for the same object compares equal while a different underlying
+  location does not.
+- **NEW**: `Parse::File#content_signature` is the overridable seam that `==`
+  uses to decide whether two files refer to the same underlying file. It returns
+  the canonical `url` today (Parse Server's S3 files adapter exposes no content
+  digest); a files-adapter shim or `Parse::File` subclass can override it to key
+  equality off a content hash (S3 ETag / sha256) in the future without touching
+  dirty tracking.
+
+### 5.2.1
+
+#### Webhook trigger handlers now receive the full Parse object
+
+Webhook trigger payloads (`beforeSave`/`afterSave`/`beforeDelete`/`afterDelete`)
+are delivered by Parse Server and authenticated by the webhook key, so they are
+trusted, server-authoritative state. Previously the payload was filtered through
+the wide mass-assignment denylist, which stripped server-issued
+`createdAt`/`updatedAt` (and other non-credential fields) before the handler
+could see them. That broke `Parse::Object#existed?` and `#new?` inside
+`afterSave` handlers — `existed?` always returned `false` and `new?` always
+returned `true`, regardless of whether the object was created or updated — and
+hid the object's timestamps and ACL from handler code.
+
+- **FIXED**: `afterSave`/`beforeSave` handlers now receive the full object as
+  Parse Server sends it (`createdAt`, `updatedAt`, `ACL`, internal fields).
+  `Parse::Object#existed?` and `#new?` are now reliable inside `afterSave`
+  handlers. (Genuine credentials — session tokens and password hashes — are
+  still stripped, and `Parse::User` continues to protect `authData` on
+  `payload.user`.)
+- **NEW**: `afterSave` handlers on an updated object now carry dirty tracking
+  relative to the prior state, so `title_changed?`, `changed`, and `changes`
+  work inside `afterSave` the same way they already did inside `beforeSave`.
+- **CHANGED**: Inbound webhook trigger payloads are now scrubbed of genuine
+  credential material only (`sessionToken`, `_hashed_password`,
+  `_password_history`) rather than the full mass-assignment denylist. Protection
+  against persisting forged privileged fields remains on the write path: a save
+  emits only declared, dirty-tracked properties, and an after-trigger response
+  is `true`/`false`, so forged `_rperm`/`_wperm`/`authData` cannot be persisted
+  through a handler. This applies only to the inbound webhook trigger payload;
+  client login/signup responses are unaffected and still return session tokens.
+- **CHANGED**: In an `afterSave` handler, `new?` now correctly returns `false`
+  (the object is already persisted) where the previous timestamp-stripping bug
+  made it return `true`. Use `existed?` to distinguish create from update inside
+  `afterSave` (`existed? == false` for a create, `true` for an update); `new?`
+  is intended for `beforeSave`.
+- **CHANGED**: Dirty-gated `after_save` side effects now fire on client/REST-
+  initiated saves where they previously silently no-op'd. With timestamps and
+  dirty tracking restored, a callback such as `after_save { notify if
+  title_changed? }` will now activate for objects created or updated via REST /
+  JS cloud code, not only for Ruby-model saves.
+
+```ruby
+Parse::Webhooks.route :after_save, "Post" do
+  post = parse_object
+
+  if post.existed?            # now reliable: false on create, true on update
+    NotificationService.changed(post) if post.title_changed?
+  else
+    post.create_default_associations!
+  end
+  true
+end
+```
+
+#### Lifecycle callbacks run in ActiveModel order for client-initiated saves
+
+Parse Server exposes no separate `beforeCreate`/`afterCreate` triggers — only
+`beforeSave` and `afterSave`. The webhook layer now runs the model lifecycle
+callbacks for a client-initiated create in the canonical ActiveModel order:
+`before_save` → `before_create` (in the `beforeSave` webhook) then
+`after_create` → `after_save` (in the `afterSave` webhook).
+
+- **FIXED**: `before_create` callbacks now run for client/REST/JS/Auth0-created
+  objects. The `beforeSave` webhook runs `before_create` after `before_save` for
+  new objects (an object with no `original`); previously `before_create` never
+  fired for non-Ruby creates, so create-time setup written as `before_create`
+  was silently skipped.
+- **FIXED**: `after_save` no longer double-fires on client-initiated saves. The
+  `beforeSave` webhook entry point previously ran the full save callback chain,
+  firing `after_save` during `beforeSave` in addition to the `afterSave`
+  webhook. It now runs the before phase only.
+- **NEW**: `Parse::Object#run_before_save_callbacks` and
+  `#run_before_create_callbacks` — the before-phase counterparts to the existing
+  `run_after_save_callbacks` / `run_after_create_callbacks`.
+- **CHANGED**: `Parse::Object#prepare_save!` is retained as a back-compat alias
+  for `run_before_save_callbacks` and now runs the before phase only (it no
+  longer also fires `after_save`). The before-phase runners honor `:if`/`:unless`
+  callback conditions and the callback terminator.
+- **NOTE**: the webhook layer runs `before_save`/`before_create` and
+  `after_create`/`after_save`, but not `before_update`/`after_update` — those
+  `:update`-specific callbacks fire only on Ruby-model saves, not for
+  client-initiated (REST/JS/Auth0) saves. Use `before_save`/`after_save` (which
+  run for every save) and branch on `existed?` if you need update-only logic.
+
 ### 5.2.0
 
 #### Retrieval layer — `Parse::Retrieval` (`Parse::RAG`)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    parse-stack-next (5.2.0)
+    parse-stack-next (5.3.0)
       activemodel (>= 6.1, < 9)
       activesupport (>= 6.1, < 9)
       connection_pool (>= 2.2, < 4)

data/README.md

@@ -4,8 +4,15 @@
 
 A full-featured Ruby client SDK for [Parse Server](http://parseplatform.org/). [parse-stack-next](https://github.com/neurosynq/parse-stack-next) is a Ruby client SDK, REST client, and Active Model ORM for [Parse Server](http://parseplatform.org/), combining a low-level API client, a query engine, an object-relational mapper (ORM), and a Cloud Code Webhooks rack application in a single gem.
 
+### What's new in 5.3
+
+- **5.3.0 — Run webhook handlers (and clients) as the calling user** — Parse Server embeds the caller's live session token in every trigger webhook fired by a logged-in user. A handler can now opt in to acting on the server *as that user* — full ACL/CLP/`protectedFields` enforcement, no master key. `payload.session_token` exposes the captured token (`nil` for master-key requests; still scrubbed from `payload.user`/`payload.object`/`as_json`/logs); `payload.user_agent` returns a client-mode `Parse::Agent`, and `payload.user_client` a non-master `Parse::Client` with the token **bound** so even raw REST calls authorize as the user. The same user-scoped client is available client-side via `Parse::User#session_client` and the `Parse::Client#become(token)` primitive, with `Parse::Client#with_session { … }` for block scoping. Backed by a new `Parse::Client.new(session_token:)` option. See [Acting as the calling user](#acting-as-the-calling-user)
+- **5.3.0 — Pluralized class-name aliases** — referencing the plural form of a model constant now resolves to that class, so `Posts.where(:author.eq => user).count` works for a class `Post`. The alias is created lazily on first reference and is the *same class object*, so every class method (`query`/`where`, `count`, `find`, `all`, scopes) works through it and `Posts.parse_class` still returns `"Post"`. Because it is the same class it adds no `Parse::Object.descendants` entry and never registers a separate Parse schema class. Classes whose name already ends in `s` are skipped by the automatic path; non-Parse plurals and typos fall through to a normal `NameError`. On by default — opt out with `Parse.pluralized_aliases = false` (or `PARSE_PLURALIZED_ALIASES=false`). For a custom plural, an `s`-ending class, or a namespaced model, call `pluralized_alias!` in the class body. See [Pluralized class-name aliases](#pluralized-class-name-aliases)
+- **5.3.0 — afterSave create reports changed fields; force_ssl-consistent file equality** — a trigger handler that keys off dirty tracking now sees every field on an `afterSave` *create*, symmetric with `afterSave` updates: the built object marks each populated data property changed (from `nil`) while `createdAt`/`updatedAt`/`ACL`/`objectId` stay clean and object readability, `new?`, and `existed?` are unchanged — so a handler that builds a payload from `*_changed?` / `changes` works uniformly across create and update. Separately, `Parse::File#==` now compares both files through the canonical `url` reader, so two files at the same location compare equal regardless of `Parse::File.force_ssl` (and `a == b` matches `b == a`), and a re-signed URL for the same object no longer reads as a change. See [Cloud Code Triggers](#cloud-code-triggers)
+
 ### What's new in 5.2
 
+- **5.2.1 — Webhook triggers receive the full Parse object** — trigger handlers (`beforeSave`/`afterSave`/…) now get the complete server object (`createdAt`/`updatedAt`, `ACL`, internal fields); only live credentials (session tokens, password hashes) are stripped. `Parse::Object#existed?` / `#new?` are reliable in `afterSave`, `afterSave` updates carry dirty tracking, and the model lifecycle runs in ActiveModel order — `before_save → before_create` then `after_create → after_save` — so `before_create` now fires for REST/JS/Auth0 creates (and `after_save` no longer double-fires). See [Cloud Code Triggers](#cloud-code-triggers)
 - **Retrieval layer — `Parse::Retrieval` (`Parse::RAG`)** — `Parse::Retrieval.retrieve(query:, klass:, k:, filter:, tenant_scope:, …)` embeds a natural-language query, runs Atlas `$vectorSearch` through the existing ACL-enforcing `find_similar`, and splits each retrieved document's text field into scored `Parse::Retrieval::Chunk`s. Chunking is presentation-only (embedding stays one-vector-per-record), via `Parse::Retrieval::Chunker::FixedSizeOverlap(size:, overlap:, by:, max_chunks_per_document:)` (subclass `Chunker::Base` for custom strategies). ACL is mongo-direct (no REST two-stage); tenant scope folds into the Atlas pre-filter
 - **`semantic_search` agent tool + `agent_searchable`** — declare `agent_searchable field:, filter_fields:` on a model to expose it to the readonly, client-safe `semantic_search` tool. The handler enforces the full agent envelope: searchable-class allowlist, recursive underscore-key refusal + filter-field allowlist on input, `field_allowlist` projection plus tenant-scope re-assertion on output, and score quantization in non-admin contexts
 - **MCP elicitation — human-in-the-loop approval** — opt in with `Parse::Agent.require_approval_for = [:write, :admin]` to require spec-native `elicitation/create` approval before destructive tool calls. A pluggable `agent.approval_gate` (reachable on the non-MCP path too) shows the dry-run diff and blocks on the client's reply; `call_method` resolves the *effective* tier from the target `agent_method`. Fails closed (no capability / no listening stream / non-streaming transport / timeout → refuse); replies are session-bound
@@ -295,6 +302,7 @@ The 1.x line is the original [`modernistik/parse-stack`](https://github.com/mode
     - [Linking and Unlinking](#linking-and-unlinking)
     - [Request Password Reset](#request-password-reset)
 - [Modeling and Subclassing](#modeling-and-subclassing)
+  - [Pluralized class-name aliases](#pluralized-class-name-aliases)
   - [Defining Properties](#defining-properties)
     - [Accessor Aliasing](#accessor-aliasing)
     - [Property Options](#property-options)
@@ -397,6 +405,7 @@ The 1.x line is the original [`modernistik/parse-stack`](https://github.com/mode
 - [Cloud Code Webhooks](#cloud-code-webhooks)
   - [Cloud Code Functions](#cloud-code-functions)
   - [Cloud Code Triggers](#cloud-code-triggers)
+    - [Trigger object state](#trigger-object-state)
   - [Mounting Webhooks Application](#mounting-webhooks-application)
   - [Register Webhooks](#register-webhooks)
 - [Parse REST API Client](#parse-rest-api-client)
@@ -1620,6 +1629,61 @@ class Commentary < Parse::Object
 end
 ```
 
+### Pluralized class-name aliases
+
+As a convenience, the plural form of a model constant resolves to that class, so the plural reads naturally at a query call site:
+
+```ruby
+class Post < Parse::Object
+  property :title, :string
+  belongs_to :author, as: :user
+end
+
+# `Posts` resolves to `Post` on first reference:
+Posts.where(:author.eq => current_user).count
+Posts.query(:title.exists => true).results
+Posts.find("abc123")
+```
+
+The alias is created lazily (via `const_missing`) the first time the plural constant is referenced, and it is the **same class object** as the singular — `Posts.equal?(Post)` is `true`. As a result:
+
+- Every class method works through it for free: `query`/`where`, `count`, `find`, `all`, and any `scope` you define.
+- `Posts.parse_class` still returns `"Post"`. The alias is purely a Ruby-constant convenience.
+- It adds no `Parse::Object.descendants` entry and **never registers a separate Parse schema class** — schema introspection and `Parse.auto_upgrade!` see exactly one class.
+
+The automatic path is deliberately conservative:
+
+- A class whose name already ends in `s` (for example `Status`, `Series`) is **skipped**, since its plural is ambiguous.
+- A plural that does not singularize to a known `Parse::Object` subclass (a typo, or `Strings` → `String`) falls through to a normal `NameError` — the SDK does not change Ruby's behavior for non-model constants.
+
+The feature is enabled by default. Opt out globally:
+
+```ruby
+Parse.pluralized_aliases = false      # programmatic
+# or
+# PARSE_PLURALIZED_ALIASES=false      # environment
+```
+
+For a custom plural, a class whose name ends in `s` that you *do* want aliased, or a namespaced model (where the alias should live on the enclosing module rather than at the top level), declare it explicitly with the `pluralized_alias!` macro. The explicit macro ignores the global flag and the `s`-ending guard:
+
+```ruby
+class Status < Parse::Object
+  pluralized_alias! :Statuses          # defines ::Statuses => Status
+end
+
+module Blog
+  class Article < Parse::Object
+    pluralized_alias!                   # defines Blog::Articles => Blog::Article
+  end
+end
+```
+
+If the target constant already exists and is not the class itself, `pluralized_alias!` raises `ArgumentError` rather than clobbering it (a code reloader swapping the class object is detected and the alias is re-pointed instead).
+
+The automatic path and the macro differ in *where* the alias constant is installed. The macro always anchors it on the class's own parent — top level for `Post`, the enclosing module for a namespaced model. The automatic path installs it on the module where the plural was first referenced (Ruby's `const_missing` fires on the referencing lexical scope), so a bare `Posts` written inside `module Blog` defines `Blog::Posts`. Both resolve to the same class; if you want a single, predictable top-level constant, prefer the macro.
+
+> **Note on reloading:** under a code reloader (for example Zeitwerk in Rails development), a model class is swapped for a fresh object on reload, but the alias constant the SDK created is not tracked by the reloader and is therefore not removed. The `pluralized_alias!` macro detects this on the next run of the class body and re-points the alias to the current class. An *automatically*-created alias, however, stays bound to the previous class object until the process restarts (`const_missing` cannot re-fire for a constant that is still defined). If you depend on the plural during development and want fully deterministic reload behavior, declare it explicitly with `pluralized_alias!`, or disable the feature with `Parse.pluralized_aliases = false`.
+
 ### Defining Properties
 Properties are considered a literal-type of association. This means that a defined local property maps directly to a column name for that remote Parse class which contain the value. **All properties are implicitly formatted to map to a lower-first camelcase version in Parse (remote).** Therefore a local property defined as `like_count`, would be mapped to the remote column of `likeCount` automatically. The only special behavior to this rule is the `:id` property which maps to `objectId` in Parse. This implicit conversion mapping is the default behavior, but can be changed on a per-property basis. All Parse data types are supported and all Parse::Object subclasses already provide definitions for `:id` (objectId), `:created_at` (createdAt), `:updated_at` (updatedAt) and `:acl` (ACL) properties.
 
@@ -4825,7 +4889,9 @@ end
 ```
 
 ### Cloud Code Triggers
-You can register webhooks to handle the different object triggers: `:before_save`, `:after_save`, `:before_delete` and `:after_delete`. The `payload` object, which is an instance of `Parse::Webhooks::Payload`, contains several properties that represent the payload. One of the most important ones is `parse_object`, which will provide you with the instance of your specific Parse object. In `:before_save` triggers, this object already contains dirty tracking information of what has been changed.
+You can register webhooks to handle the different object triggers: `:before_save`, `:after_save`, `:before_delete` and `:after_delete`. The `payload` object, which is an instance of `Parse::Webhooks::Payload`, contains several properties that represent the payload. One of the most important ones is `parse_object`, which will provide you with the instance of your specific Parse object.
+
+The `parse_object` handed to your handler is the **full object as Parse Server sent it** — `createdAt`/`updatedAt`, `ACL`, and internal fields all survive (only live credentials — session tokens and password hashes — are stripped; `Parse::User` additionally protects `authData` on `payload.user`). Both `:before_save` and `:after_save` objects carry **dirty tracking** of what changed (`name_changed?`, `changes`), and `Parse::Object#existed?` / `#new?` are reliable inside `:after_save`. See [Trigger object state](#trigger-object-state) below.
 
 ```ruby
   # recommended way
@@ -4862,6 +4928,60 @@ For any `after_*` hook, return values are not needed since Parse does not utiliz
 > for saves from other clients (JS / iOS / REST), the webhook runs them, since
 > the SDK never had the chance.
 
+#### Trigger object state
+
+Because the trigger payload is server-authoritative, the `parse_object` your
+handler receives is the complete object, and the usual `Parse::Object`
+introspection works inside the trigger:
+
+| What you want to know | In `:before_save` | In `:after_save` |
+|---|---|---|
+| Is this a create or an update? | `parse_object.new?` (`true` = create) | `parse_object.existed?` (`false` = create) or `payload.original.nil?` |
+| What changed? | `name_changed?`, `changes`, `changed` | `name_changed?`, `changes`, `changed` (relative to the prior state) |
+| Server timestamps | not yet assigned (`new?` create) | `created_at` / `updated_at` populated |
+| The prior stored values | `payload.original_parse_object` | `payload.original_parse_object` |
+
+Use `new?` in `:before_save` and `existed?` in `:after_save`. In `:after_save`
+the object is already persisted, so `new?` is `false` for both creates and
+updates — `existed?` (`created_at != updated_at`) is the create/update signal,
+equivalently `payload.original.nil?`.
+
+```ruby
+Parse::Webhooks.route :after_save, :Post do
+  post = parse_object
+  if post.existed?
+    Search.reindex(post) if post.title_changed?   # update
+  else
+    post.create_default_associations!             # first save
+  end
+  true
+end
+```
+
+**Lifecycle callback order.** Parse Server has no separate `beforeCreate` /
+`afterCreate` triggers — only `beforeSave` and `afterSave`. The SDK runs your
+model's ActiveModel callbacks in canonical order across the two webhooks:
+
+```
+beforeSave webhook :  before_save  →  before_create   (before_create only for new objects)
+   [Parse Server persists]
+afterSave  webhook :  after_create →  after_save      (after_create only for new objects)
+```
+
+So a model `before_create` / `after_create` callback runs for objects created by
+**any** client (REST / JS cloud code / Auth0 / iOS), not just Ruby-model saves —
+provided the corresponding trigger is registered with Parse Server (see
+[Register Webhooks](#register-webhooks)). These callbacks fire **once** per save;
+Ruby-SDK-initiated saves run them locally and the webhook skips them to avoid
+double-firing. `:if`/`:unless` conditions on these callbacks are honored.
+
+> **`before_update` / `after_update` do not run from webhooks.** The webhook
+> layer runs `before_save` / `before_create` / `after_create` / `after_save`
+> only. The `:update`-specific callbacks fire on Ruby-model saves but **not**
+> for client-initiated (REST / JS / Auth0) saves, because Parse Server has no
+> `beforeUpdate` / `afterUpdate` trigger. For update-time logic that must run
+> for all clients, use `before_save` / `after_save` and branch on `existed?`.
+
 > **Keep `after_save` handlers fast.** Parse Server **waits** for the `after_save`
 > webhook response before returning to the saving client (only LiveQuery events
 > are truly fire-and-forget), so a slow handler adds latency to that client's
@@ -4872,6 +4992,80 @@ For any `after_*` hook, return values are not needed since Parse does not utiliz
 > most for client-initiated saves, where the callback runs inside the webhook —
 > Ruby-SDK saves run it in-process after their own REST response instead.
 
+#### Acting as the calling user
+
+Parse Server includes the caller's live session token (`user.sessionToken`) in
+every trigger webhook fired by a logged-in user (it is absent for a master-key
+request). A handler can opt in to acting on the server **as that user** —
+authorized by Parse Server with full ACL, CLP, and `protectedFields`
+enforcement — instead of reaching for the application master key. Three opt-in
+handles are available on the `payload`:
+
+| Handle | Returns | `nil` when |
+|---|---|---|
+| `payload.session_token` | the caller's raw token (`String`) | master-key request (no user) |
+| `payload.user_agent(**opts)` | a non-master `Parse::Agent` in **client mode**, token bound | no token |
+| `payload.user_client` | a non-master `Parse::Client` with the token **bound** | no token |
+
+```ruby
+Parse::Webhooks.route :after_save, :Post do
+  next true unless session_token?            # master-key save → no caller token
+
+  # A client-mode Parse::Agent scoped to the caller (read tools only unless
+  # you pass allow_mutations: true). ACL/CLP enforced; no master-key fallback.
+  visible = user_agent.execute(:query_class, class_name: "Post", limit: 20)
+
+  # …or a raw user-scoped Parse::Client. The token is BOUND, so plain REST
+  # calls authorize as the user with no per-call session_token: argument:
+  mine = user_client.request(:get, "classes/Post").result
+  true
+end
+```
+
+The token is captured before the payload's credential scrubbing runs, so it is
+still removed from `payload.user` / `payload.object` and never appears in
+`payload.as_json`, `payload.inspect`, or the request log. `user_client` binds it
+via the `Parse::Client.new(session_token:)` option, applied as the
+lowest-priority auth fallback — an explicit per-call `session_token:`, a
+`Parse.with_session` block, or an explicit `use_master_key: true` all still take
+precedence. This applies to **webhook-delivered** triggers (including the model
+`webhook :before_save` DSL, which is HTTP-delivered); a genuine in-process
+ActiveModel `before_save :method` callback has no incoming request and therefore
+no caller token.
+
+The same user-scoped client is available on the **client side**. Two shapes:
+
+```ruby
+# 1. A client object you can pass around (carries the user's token + the
+#    server connection, no master key):
+client = Parse::User.login(username, password).session_client
+Parse::Query.new("Post", client: client).results        # runs as the user
+# (Parse.client.become(token) builds the same thing from any token.)
+
+# 2. A block that runs ordinary model operations as the user, without
+#    threading session_token: through each call:
+Parse::User.login(username, password).with_session do
+  Post.query.count            # counts only the user's readable Posts
+  Post.create(title: "Hi")    # created under the user's permissions
+end
+```
+
+`with_session` (on a `Parse::User`, a `Parse::Client`, or `Parse.with_session`)
+scopes by binding the token as the ambient session — it authorizes
+**REST-routed** operations (`find` / `get` / `count` / `save`) as the user. It
+does **not** scope mongo-direct queries (`results_direct`, `aggregate`, Atlas
+search): those resolve auth from the query's own `session_token:` / `acl_user:`
+and otherwise run in **master** mode, so scope them explicitly with a per-query
+`session_token:` or a scoped `Parse::Agent`. (To run a query as a user *without*
+a token — via the master key and SDK-side ACL simulation — use
+`Parse::Query#scope_to_user(user)`.) `Parse::Client#anonymous` builds the same
+non-master client with no token, for an explicitly unauthenticated request.
+
+To explore a server as a specific user from this repo, `rake client:console`
+opens an IRB session whose default client is a non-master client bound to a user
+(session token, login, or anonymous), so every query in the session runs with
+that user's ACL/CLP — with `whoami` and `as_master { … }` helpers.
+
 `before_save` and `before_delete` hooks have special functionality and multiple ways to halt operations:
 
 1. **Using `error!` method**: Calling `error!` will return an error response to Parse Server