parse-stack-next 5.7.3 → 5.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4017efda309de14faf52b86e26274cc097ee029d282a975f0144e324ac68250
-  data.tar.gz: e46cbf422955acc46ef7ceff8348a564712a9109051511dfec1bd2dce96356f0
+  metadata.gz: 2d06f0d8932e328bae92fde22a568b9669614a02e75a5deed1a220884213d43e
+  data.tar.gz: edaaf3bb456a5396fdc08706188ca07d66aba66b17c7fce95220f130041644d8
 SHA512:
-  metadata.gz: 1cee46e278c9ad77fab0d4f2869636c623b43e9e1b7d2ea0ea77f92be9ad8f6631bb6e5f92421997f92d42ba73470db659486595fe0993a50de93140eb6051fb
-  data.tar.gz: 36322b4f93132dd277476d999fc71511324d5a726979896ae08e4f6aea31d3aa4454fd41910a1c7758d229c9ff1000cb43de12ffaf8f795403e1ab7cf96f71ef
+  metadata.gz: 202606fe6edad9aafda2d48a216addfca376d24b01f1a8a39febce4fa511fcf5253f736632bf7aeff64645fe398d015fccb694ddf622688f3a78a6431b570ed2
+  data.tar.gz: a09f557be7a37d9f12937e0c70da314c617bd8ec18993cef2952336b7b55b6d1d9bbe3e0381933b70a4f3bdc3b2dcf3a71125edf83c460f5d15d4b0c58d3b3c8

data/CHANGELOG.md

@@ -1,5 +1,195 @@
 ## parse-stack-next Changelog
 
+### 5.7.5
+
+#### MongoDB 9.0 support
+
+Parse Server 9.10 and the SDK's mongo-direct paths run against MongoDB 9.0.
+This release moves the test stack to 9.0, re-runs reads that 9.0 kills
+mid-flight, and documents the server-side behavior changes that reach SDK
+callers.
+
+- **CHANGED**: The integration test stack runs `mongo:9` by default. Set
+  `MONGO_VERSION=8` to run it against the previous major. A data volume
+  written by one major is not guaranteed to start under another, so switch
+  with `docker-compose down -v` or a separate `PSNEXT_PREFIX`. Atlas Local
+  stays on 8.0, since no 9.x image of it is published yet.
+- **CHANGED**: Applications using `Parse::MongoDB`, `Parse::AtlasSearch`,
+  or the `*_direct` query methods against a 9.0 server should require the
+  `mongo` driver 2.26 or newer, which adds handling for MongoDB 9.0's
+  overload (Intelligent Workload Management) errors. The gem's development
+  lock is already on 2.26.0.
+- **NEW**: Mongo-direct reads (`Parse::MongoDB.aggregate`,
+  `Parse::MongoDB.find`, everything routed through them such as
+  `results_direct`, and `Parse::AtlasSearch` searches) re-run a query the
+  server killed with `QueryPlanKilled` (code 175; the 9.0 release notes call
+  it a `QueryKilledError`). MongoDB 9.0 kills a running query this way when an
+  indexed field it references becomes multikey because a concurrent write
+  stored an array there. The read is retried up to
+  `Parse::MongoDB::QUERY_KILLED_RETRIES` (2) times before the error
+  propagates. Retries are immediate, since the kill means a concurrent write
+  changed the index rather than that the server is overloaded. Each retry
+  emits a `parse.mongodb.query_killed_retry` notification. Other driver
+  errors are not retried.
+
+#### Voyage `voyage-code-4` and contextualized chunk embeddings
+
+- **NEW**: `Parse::Embeddings::Voyage` accepts `voyage-code-4` (1024
+  native, Matryoshka 256/512/1024/2048, 32k tokens). It routes through
+  `/v1/embeddings` like the other text models.
+- **NEW**: `voyage-context-4` and `voyage-context-3` are supported. These
+  models embed each chunk together with the document it came from, through
+  Voyage's `/v1/contextualizedembeddings` endpoint. `embed_text` sends each
+  string as a one-chunk document, which is the right shape for queries. The
+  `embed` class macro uses the same path, so stored fields are embedded
+  without surrounding-document context; call `embed_chunks` for that. These
+  models default to `embed_batch_size: 32` rather than 128, since every input
+  is a whole document and Voyage caps a request at 120k tokens.
+- **NEW**: `Voyage#embed_chunks(documents, input_type:)` takes one Array of
+  chunk Strings per document and returns one Array of chunk vectors per
+  document, aligned with the input. It enforces Voyage's per-request limits
+  (1,000 documents and 16,000 chunks) before any network call, and raises
+  `BadRequestError` on a model that is not contextualized. The endpoint has
+  no `truncation` field, so none is sent for these models. Large inputs are
+  sent as several requests, grouping whole documents so each response stays
+  within the provider's response-size cap; a document is never split across
+  requests. That split is sized by response vectors, not input tokens, so
+  it does not by itself keep a request under Voyage's 120k-token input cap.
+- **NEW**: `Parse::Retrieval::Reranker::Voyage` wraps Voyage's `/v1/rerank`
+  and plugs into `Parse::Retrieval.retrieve(rerank:)` like the Cohere
+  reranker. It defaults to `rerank-3` and accepts `rerank-3-lite` and the
+  2.5 and 2 series. An Atlas model API key (`al-` prefix) routes to the
+  Atlas Embedding and Reranking API automatically. `truncation: false`
+  makes over-length inputs an error instead of truncating them.
+
+#### MCP server speaks protocol version 2025-11-25
+
+- **NEW**: The MCP server negotiates `2025-11-25` and advertises it as its
+  preferred version; `2025-06-18`, `2025-03-26`, and `2024-11-05` are still
+  accepted. `serverInfo` now carries `title` and `description`.
+- **NEW**: `completion/complete` is implemented and the `completions`
+  capability advertised. Prompt arguments named `class_name`,
+  `parent_class`, `child_class`, or `classes`, and the `{className}`
+  variable of the `parse://` resource templates, complete to the class
+  names the connecting agent can see. `group_by` and `pointer_field`
+  complete to field names of the class given in the request's
+  `context.arguments`. Candidates come from the same tools that back
+  `resources/list` and `get_schema`, so hidden classes and fields are never
+  offered. Each completion runs those tools through `agent.execute`, so it
+  counts against the agent's rate limiter; clients should debounce.
+- **NEW**: `logging/setLevel` is implemented. On a streaming request,
+  `notifications/message` events at or above the session's level are sent
+  on that request's response stream. Nothing is sent until the client sets a
+  level. The `logging` capability is advertised only by `MCPRackApp` with
+  streaming on, since no other transport can deliver the messages. A level
+  can be set only for a session that was initialized by the same principal,
+  so one caller cannot change another session's level. Tools emit messages with
+  `agent.log(level, data, logger:)`, and failed tool calls are logged at
+  `warning` with the tool name and error code.
+- **FIXED**: Approval prompts are sent only to clients that accept form-mode
+  elicitation. Under `2025-11-25` a client declares its modes, and one that
+  declares only `url` would reject the form; the approval was then refused
+  and reported as a user cancellation. Such a client is now treated like one
+  without elicitation, so the destructive call is refused up front with
+  that reason. An empty `elicitation: {}` (the earlier shape) still means
+  form support.
+- **CHANGED**: `initialize` with an `Mcp-Session-Id` already bound to a
+  different principal is refused with 403 instead of rebinding the session
+  to the new caller. Previously, knowing another session's id was enough to
+  take over its owner binding, and with it the listening stream, the
+  recorded elicitation capability, and the log level. The owning principal
+  can still re-initialize its own session.
+- **CHANGED**: A `tools/call` whose `arguments` is not a JSON object now
+  returns a tool result with `isError: true` instead of an internal error,
+  as `2025-11-25` requires for input validation failures.
+
+#### `server/discover` no longer fails the MCP version check
+
+- **FIXED**: Newer MCP clients send `server/discover` before `initialize`,
+  carrying a protocol version this server does not support. The transport
+  rejected it with a 400 before it reached the dispatcher, so the client
+  treated the server as broken instead of falling back to `initialize`. The
+  request now reaches the dispatcher, which answers `-32601`, and the client
+  negotiates a supported version through `initialize`. Other methods still
+  get a 400 for an unsupported version.
+
+#### Embedding cache entries are separated by deployment
+
+- **FIXED**: `Parse::Embeddings::Cache` keyed entries by provider class,
+  model, dimensions, and input type, but not by endpoint. Two providers of
+  the same class and model pointed at different deployments (two
+  self-hosted `LocalHTTP` servers serving different weights under one model
+  name, or a provider behind a proxy) shared cache entries, so one could be
+  served the other's vector for the same query. The key now includes the
+  provider's deployment identity: the endpoint's scheme, host, non-default
+  port, and path, never credentials, userinfo, or a query string. Built-in
+  HTTP providers derive it from their `base_url`; `Provider#cache_identity`
+  can be overridden. Providers with no endpoint keep their existing keys,
+  so custom providers are unaffected. Existing cached entries for built-in
+  providers miss once and are re-filled.
+
+#### Test infrastructure
+
+- **CHANGED**: Development and CI use Bundler 4.0.22. The lockfile now
+  includes gem checksums; dependency versions are unchanged.
+- **CHANGED**: The CI matrix's `3.5` lane, which resolved to a 2025
+  `3.5.0preview1` build, is replaced by Ruby 4.0. The unit suite passes on
+  Ruby 4.0.6.
+- **NEW**: Snapshot fixtures pin the `$vectorSearch` pipeline (master,
+  user-session, strict-role, and caller-filter scopes), the native
+  `$rankFusion` pipeline (including that the ACL `$match` and final `$limit`
+  run after fusion), and `clp_scope` protected-field resolution and
+  redaction.
+- **FIXED**: A streaming heartbeat test asserted how many heartbeats fired
+  before a tool's first progress report, which depends on scheduler timing
+  and failed intermittently on slower CI runners. It now asserts the
+  property under test: no heartbeat follows the first report.
+
+### Behavior Notes
+
+These are MongoDB 9.0 server changes, not SDK changes. They apply to REST
+queries (Parse Server passes them to MongoDB) and to mongo-direct queries
+alike.
+
+- Equality and range comparisons against `null` (`$eq`, `$ne`, `$in`,
+  `$nin`, `$gte`, `$lte`, and `$lookup` equality) treat a dotted path that
+  traverses an array and resolves to no non-null value as `null`. For
+  `{ a: [] }` or `{ a: [1] }`, a query for `"a.b"` equal to `nil` now
+  matches, and `"a.b"` not equal to `nil` no longer does.
+- `$group` rejects an accumulator with an empty field name.
+- A query fails with `QueryPlanKilled` if an indexed field becomes
+  multikey while it runs. The SDK's mongo-direct reads re-run it (see
+  above); REST queries surface Parse Server's error.
+- `$where`, `$function`, and `$accumulator` are no longer deprecated in
+  9.0. The SDK continues to block them in every pipeline and constraint it
+  validates.
+
+### 5.7.4
+
+#### Reset connections are retried instead of surfacing a raw Faraday error
+
+A focused fix release for the request retry mechanism. A stale keep-alive
+connection (a pooled persistent connection closed by the server or a load
+balancer after idling) failed the next request with a raw
+`Faraday::ConnectionFailed` / `Errno::ECONNRESET` instead of retrying, even
+though an immediate re-send on a fresh connection succeeds. Reset connections
+now retry under the same idempotency rules as read timeouts.
+
+- **FIXED**: `Parse::Client#request` now rescues `Faraday::ConnectionFailed`
+  and inspects the wrapped cause. Reset-class causes (`Errno::ECONNRESET`,
+  `Errno::EPIPE`, `Errno::ECONNABORTED`, and the `EOFError` raised when the
+  remote end closes a keep-alive socket cleanly) are transient, so idempotent
+  requests (GET, DELETE, op-free PUT, and any write covered by asserted
+  server-side request-id dedup) retry with the standard backoff. Connection
+  refused and DNS failures keep the previous fail-fast behavior and propagate
+  the raw `Faraday::ConnectionFailed` with no retry latency.
+- **CHANGED**: A reset connection that persists through the whole retry budget
+  now raises `Parse::Error::ConnectionError` (consistent with the read-timeout
+  path) instead of the raw `Faraday::ConnectionFailed`. Code that rescued
+  `Faraday::ConnectionFailed` to catch resets should rescue
+  `Parse::Error::ConnectionError` instead; refused and DNS failures still
+  raise `Faraday::ConnectionFailed`.
+
 ### 5.7.3
 
 #### Stored values can no longer drive the operator's terminal

data/README.md

@@ -6,6 +6,9 @@ A full-featured Ruby client SDK for [Parse Server](http://parseplatform.org/). [
 
 ## What's new in 5.7
 
+- **5.7.5: MongoDB 9.0 support.** The test stack runs MongoDB 9 by default (`MONGO_VERSION=8` selects the previous major), and use the `mongo` driver 2.26 or newer for 9.0's overload handling. MongoDB 9.0 changes how `null` comparisons treat dotted paths through arrays; see the behavior notes in [CHANGELOG.md](./CHANGELOG.md)
+- **5.7.5: `voyage-code-4` and contextualized chunk embeddings.** The Voyage provider accepts `voyage-code-4`, `voyage-context-4`, and `voyage-context-3`. `Voyage#embed_chunks` embeds whole chunked documents so each chunk's vector carries its document's context. See [CHANGELOG.md](./CHANGELOG.md)
+- **5.7.5: Voyage reranker and MCP 2025-11-25.** `Parse::Retrieval::Reranker::Voyage` adds `rerank-3` and `rerank-3-lite` reranking, including through the Atlas endpoint. The MCP server negotiates protocol `2025-11-25` and adds `completion/complete` (class and field names scoped to the agent) and `logging/setLevel`. Mongo-direct reads re-run queries MongoDB 9.0 kills mid-flight. See [CHANGELOG.md](./CHANGELOG.md)
 - **5.7.0: Reserved, app-scoped cache keyspace.** `Parse::Cache::Keyspace` lays out response, identity, and role-cache keys on a shared backend (`parse-stack:v1:<app_scope>[:<namespace>]:<family>[:T:<tenant>]:<rest>`) and owns the glob patterns that clear them again, so key generation and eviction can no longer drift apart. `app_scope` is a digest of the application id and server URL, so two apps sharing one Redis no longer collide. Enable with `cache_keyspace: true` on `Parse.setup`; left unset, behavior is unchanged. See [CHANGELOG.md](./CHANGELOG.md)
 - **5.7.0: `clear_cache!` stops falling back to `FLUSHDB`.** With `cache_keyspace: true`, `Parse::Client#clear_cache!` performs a scoped SCAN inside the client's own keys instead of flushing the whole database, which previously could destroy co-tenant data and drop `first_or_create!` create-locks on a shared Redis. `flush_db!` remains the explicit opt-in for a full flush. See [CHANGELOG.md](./CHANGELOG.md)
 - **5.7.0: Response-cache auth separation enforced by construction.** `Parse::Cache::Keyspace#cache_key` now requires an `auth:` discriminator for the response-cache family and refuses to build a key without one, so a master-key body and a session-token body can no longer land under the same key by accident. A non-GET write now invalidates every auth variant of a resource in one scoped pattern instead of only the variants the process has already seen. See [CHANGELOG.md](./CHANGELOG.md)

data/docs/atlas_vector_search_guide.md

@@ -120,8 +120,11 @@ providers:
   `{ type: "image_url", image_url: { url: ... } }` content rows.
 * `Parse::Embeddings::Voyage` — voyage-4 family (`voyage-4-large` 2048,
   Matryoshka; `voyage-4` 1024; `voyage-4-lite` 512; `voyage-4-nano` 256),
-  voyage-3 family, domain models (`voyage-code-3`, `voyage-finance-2`,
-  `voyage-law-2`), and `voyage-multimodal-3` (1024-dim, 32k token
+  voyage-3 family, domain models (`voyage-code-4`, `voyage-code-3`,
+  `voyage-finance-2`, `voyage-law-2`), contextualized chunk models
+  (`voyage-context-4`, `voyage-context-3`; route to
+  `/v1/contextualizedembeddings`, with whole chunked documents embedded
+  through `embed_chunks`), and `voyage-multimodal-3` (1024-dim, 32k token
   context, routes to `/v1/multimodalembeddings` with the wrapped
   `{inputs: [{content: [{type: "text", text: ...}]}]}` envelope for
   text and `{type: "image_url", image_url: <url>}` content rows for
@@ -330,7 +333,8 @@ Every `text:`-overload query funnels through one embed path
 ```ruby
 # Opt-in query-embed cache: repeated identical queries skip the
 # provider round-trip. Keyed by (provider, model, dimensions,
-# input_type, SHA-256(input)) — plaintext never lands in the store.
+# input_type, deployment endpoint, SHA-256(input)); plaintext and
+# credentials never land in the store.
 Parse::Embeddings::Cache.enable!(max_entries: 2048, ttl: 600)
 Parse::Embeddings::Cache.stats   # => { enabled:, hits:, misses:, size: }
 
@@ -451,6 +455,69 @@ embed-time chunking), use one of these patterns:
    similarity search against the chunk collection, then hydrate
    parents as needed.
 
+### Contextualized chunk embeddings (`voyage-context-4`)
+
+An ordinary embedding of a chunk sees only that chunk. "It ships Friday."
+embeds the same no matter which product the surrounding document is
+about. Voyage's contextualized models (`voyage-context-4`,
+`voyage-context-3`) embed every chunk together with the rest of its
+document, so each chunk vector also carries what the document is about.
+
+To get that, send a document's chunks together with `embed_chunks`:
+
+```ruby
+voyage = Parse::Embeddings::Voyage.new(
+  api_key: ENV.fetch("VOYAGE_API_KEY"),
+  model:   "voyage-context-4",           # 1024 dims; 256/512/2048 via dimensions:
+)
+
+documents = [
+  ["The Atlas release slipped a week.", "It ships Friday."],   # one document, two chunks
+  ["Billing moves to the new provider.", "It ships Friday."],
+]
+vectors = voyage.embed_chunks(documents, input_type: :search_document)
+# => [[vec_a1, vec_a2], [vec_b1, vec_b2]]  one Array per document, aligned with its chunks
+# vec_a2 != vec_b2: the same sentence, embedded with different documents.
+
+# Store each chunk vector on its own record. The chunk class declares the
+# vector property but NOT the `embed` macro: `embed :content` would
+# recompute the vector from `content` alone on save, silently replacing the
+# contextual vector with an ordinary one.
+class PostChunk < Parse::Object
+  belongs_to :post
+  property :content, :string
+  property :embedding, :vector, dimensions: 1024
+end
+
+documents.zip(vectors).each do |chunks, chunk_vectors|
+  chunks.zip(chunk_vectors).each { |text, vec| PostChunk.create!(content: text, embedding: vec) }
+end
+
+# Queries are single strings: embed_text sends each as a one-chunk document.
+query_vec = voyage.embed_text(["when does it ship?"], input_type: :search_query).first
+PostChunk.find_similar(vector: query_vec, k: 5)
+```
+
+Two things to know:
+
+* **The `embed` macro does not contextualize.** It sends each record's
+  source text through `embed_text`, which treats every input as its own
+  one-chunk document. Registering a context model as an `embed` provider
+  works, but the stored vectors carry no surrounding-document context.
+  Use `embed_chunks` when chunk-level context is the point.
+* **Request sizing is partly handled for you.** Voyage caps one request
+  at 1,000 documents, 16,000 chunks, and 120k tokens. `embed_chunks`
+  checks the document and chunk caps before sending, and splits large
+  inputs across several requests by whole document (a document's chunks
+  always travel together) so that each **response** stays under the
+  SDK's response-size cap. That split is sized by the vectors coming
+  back, not by tokens going out, so it does **not** guarantee a request
+  stays under the 120k input-token cap. The SDK has no tokenizer to
+  check that; keep long documents to a few per call, and expect a
+  `BadRequestError` from Voyage if a request exceeds it. Context models
+  default to `embed_batch_size: 32` to keep `embed_text` batches clear of
+  the token cap for typical inputs, which is a heuristic, not a check.
+
 ---
 
 ## Retrieval (RAG)
@@ -541,6 +608,19 @@ when the cluster does not support it; the default `:rrf` always fuses
 client-side, which is the fully-enforced, deterministic path. `$rankFusion`
 is admitted to `PipelineSecurity::ALLOWED_STAGES` for the native path.
 
+*Status:* the native path is shipped and its pipeline shape is pinned by
+unit and snapshot tests. Unlike the client-side path, where each branch
+enforces ACL and CLP before fusion, the native path applies the ACL
+`$match` **after** `$rankFusion`: the stage fuses the unfiltered candidate
+sets, then rows the caller cannot read are dropped. To keep a scoped caller
+from being underfilled by those drops, the branches request a wider
+candidate window and the final `$limit` runs after the ACL match; a caller
+who can read only a small fraction of the collection can still receive
+fewer than `k` results. Fused scores are recomputed from surviving rows so
+an unreadable row's rank does not leak through. It has not yet been
+validated end to end against a live Atlas cluster, which is why it stays
+opt-in rather than the default.
+
 `Parse::Retrieval.retrieve(hybrid: true, ...)` routes through
 `hybrid_search` and chunks the fused results; pass `hybrid: { lexical:,
 vector:, fusion: }` to configure the branches. Tenant scope is folded into
@@ -565,6 +645,27 @@ chunks = Parse::Retrieval.retrieve(
 # Reranked chunks' score is the cross-encoder relevance_score.
 ```
 
+Voyage's rerankers plug in the same way. `rerank-3` is the default and
+`rerank-3-lite` is the cheaper option. An Atlas model API key (`al-`
+prefix) routes to MongoDB's Atlas Embedding and Reranking API
+automatically, exactly like the Voyage embeddings provider:
+
+```ruby
+reranker = Parse::Retrieval::Reranker::Voyage.new(
+  api_key: ENV.fetch("VOYAGE_API_KEY"),   # or an Atlas "al-..." key
+  model:   "rerank-3-lite",
+  truncation: false,                      # over-length input raises instead of truncating
+)
+chunks = Parse::Retrieval.retrieve(
+  query: "reset my password", klass: Article, k: 30,
+  rerank: reranker, rerank_top_n: 5,
+)
+
+# Or directly, outside retrieve:
+reranker.rerank(query: "capital of France", documents: docs, top_n: 3)
+# => [#<struct Result index=1, relevance_score=0.91>, ...]
+```
+
 `Reranker::Fixture` is a deterministic, zero-network reranker (lexical
 token overlap) for tests. The `Reranker::Base` protocol validates inputs,
 bounds `top_n`, rejects out-of-range indices, and sorts descending —
@@ -655,8 +756,9 @@ envelope. See the [MCP guide's Token Economy section](./mcp_guide.md#token-econo
 
 `embed_image` is the image-source counterpart to `embed`. The source
 property must be `:file`-typed; the target must be a `:vector` property
-whose declared `provider:` supports multimodal input (currently
-`:voyage` with `voyage-multimodal-3`, or `:cohere` with `embed-v4.0`).
+whose declared `provider:` supports multimodal input (`:voyage` with
+`voyage-multimodal-3.5` or `voyage-multimodal-3`, or `:cohere` with
+`embed-v4.0`).
 
 Two fetch modes, selected per declaration with `source:`:
 
@@ -782,7 +884,17 @@ Direct provider calls accept the same shape:
 
 ### Save-side semantics
 
-* Digest is the **SHA-256 of the URL String**, not the file bytes.
+* **Private buckets.** When the file adapter returns signed URLs (S3 or GCS
+  with `presignedUrl: true`), `file.url` holds the canonical URL with the
+  signature stripped and the signed form is kept in `file.presigned_url`.
+  Recompute fetches through `file.presigned_url` while it is still valid
+  (for both `source: :url` and `source: :bytes`) and falls back to the bare
+  URL otherwise, so a private object is reachable without making the
+  bucket public. Make sure the URL's lifetime outlasts the save: an expired
+  signature falls back to the bare URL, which a private bucket refuses.
+* Digest is the **SHA-256 of the canonical URL String** (signature
+  stripped), not the file bytes, so a save that only rotates the
+  signature does not re-embed.
   Replacing the `Parse::File` with one pointing at a different URL
   re-embeds; resaving the same URL is a no-op (zero provider calls).
   Parse-managed file URLs are stable unless overwritten in place — if
@@ -841,9 +953,12 @@ each row's digest sibling (so the save-path recompute cannot elide the
 provider call), and saves. Unlike `embed_pending!` — which only fills
 NULL vectors — `reembed!` recomputes populated rows too. Run it with a
 master-key client (or pass `save_opts:` with a session token that can
-write every row). Each row's save makes one provider call; pace bulk
-runs against provider rate limits (see `BatchEmbedder` below for the
-pattern, or just throttle the loop).
+write every row). `batch_size:` is the query page size: it controls how
+many records are fetched per round, not how many inputs go into a provider
+request. Each row's save makes its own provider call; pace bulk runs
+against provider rate limits (see `BatchEmbedder` below for the pattern,
+or just throttle the loop). `embed_pending!(batch_size:)` pages the same
+way.
 
 ### Changed-width migrations: dual-field workflow
 
@@ -932,7 +1047,7 @@ Payload contract (keys always present; values may be nil):
 | `:input_count` | `Integer`     | batch size                                                              |
 | `:input_type`  | `Symbol`      | `:search_query` / `:search_document`                                    |
 | `:total_tokens`| `Integer`/nil | provider-reported usage; nil for Fixture and providers without usage    |
-| `:cached`      | `Boolean`     | always false in v5.0; reserved for v5.1 embed cache                     |
+| `:cached`      | `Boolean`     | true when `Parse::Embeddings::Cache` served the vector (no provider call) |
 | `:error`       | `String`/nil  | `exception.class.name` when the block raised — class name only         |
 
 Notes:

data/docs/mcp_guide.md

@@ -766,6 +766,87 @@ out-of-band / clustered publisher that needs the lower-level `publish` seam.
 
 ---
 
+## Argument Completion (`completion/complete`)
+
+The server advertises the `completions` capability, so clients that support
+it (MCP Inspector, IDE integrations) can autocomplete prompt arguments and
+resource-template variables:
+
+| Argument | Completes to |
+|---|---|
+| `class_name`, `parent_class`, `child_class` on any prompt; `{className}` in `parse://{className}/...` | Class names the connecting agent can see |
+| `classes` (comma-separated) | The last segment of the list |
+| `group_by`, `pointer_field` | Field names of the class named by `class_name` (or `child_class`) in the request's `context.arguments` |
+
+```json
+{"jsonrpc":"2.0","id":7,"method":"completion/complete","params":{
+  "ref":{"type":"ref/prompt","name":"count_by"},
+  "argument":{"name":"group_by","value":"st"},
+  "context":{"arguments":{"class_name":"Post"}}}}
+```
+
+```json
+{"jsonrpc":"2.0","id":7,"result":{"completion":{"values":["status","state"],"total":2,"hasMore":false}}}
+```
+
+Candidates come from the same `get_all_schemas` / `get_schema` tools that back
+`resources/list`, so `agent_hidden` classes, the `classes:` allowlist, and
+`agent_fields` all apply: a completion never offers a name the agent could not
+already see. Each completion is a tool call for rate-limiting and audit
+purposes, so clients that complete on every keystroke should debounce. Custom
+prompts get class-name completion automatically by naming an argument
+`class_name`, `parent_class`, `child_class`, or `classes`.
+
+---
+
+## Logging (`logging/setLevel`)
+
+On `MCPRackApp` with streaming on, the server advertises the `logging`
+capability. A client opts in by setting a minimum level for its session; from
+then on, log messages at or above that level ride the response stream of each
+streamed request as `notifications/message`, ahead of the final response.
+Nothing is sent before the client sets a level, and the WEBrick `MCPServer`
+and non-streaming Rack mounts do not advertise the capability at all.
+
+```json
+{"jsonrpc":"2.0","id":3,"method":"logging/setLevel","params":{"level":"warning"}}
+```
+
+Built-in behavior: a failed `tools/call` logs at `warning` with the tool name
+and error code. Custom tools log through the agent:
+
+```ruby
+Parse::Agent::Tools.register(
+  name:        :reindex_posts,
+  description: "Rebuild the Post search index",
+  parameters:  { type: "object", properties: {} },
+  permission:  :readonly,
+  handler: lambda do |agent, **_args|
+    agent.log(:info, { "step" => "scanning", "rows" => 1200 }, logger: "reindex")
+    # ...
+    agent.log(:warning, "3 rows skipped: missing title")
+    { reindexed: 1197 }
+  end,
+)
+```
+
+`agent.log` takes an RFC 5424 level (`:debug`, `:info`, `:notice`,
+`:warning`, `:error`, `:critical`, `:alert`, `:emergency`; anything else
+raises `ArgumentError` on every transport) and any JSON-serializable data.
+It is a no-op when no client is listening. Do not log secrets or rows the
+agent's scope cannot read; the message goes to whoever holds the session.
+
+A level is stored per `Mcp-Session-Id` and can be set only by the principal
+that initialized that session, so one caller cannot silence or flood another
+session's logs. `DELETE` on the session forgets it.
+
+> **Spec note.** MCP `2026-07-28` removes `logging/setLevel` in favor of a
+> per-request log level in `_meta` and deprecates the logging feature. This
+> server targets `2025-11-25` and earlier, where `logging/setLevel` is the
+> mechanism. `agent.log` is the stable API either way.
+
+---
+
 ## Built-in Agent Hardening & Telemetry
 
 5.2 adds several agent-side controls, all configured on `Parse::Agent`:

data/lib/parse/agent/log_levels.rb

@@ -0,0 +1,11 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  class Agent
+    # RFC 5424 severities used by MCP logging, least to most severe. Shared
+    # by {Parse::Agent#log} and {Parse::Agent::MCPDispatcher} so a level is
+    # validated the same way whether or not a transport is attached.
+    LOG_LEVELS = %w[debug info notice warning error critical alert emergency].freeze
+  end
+end