parse-stack-next 5.4.1 → 5.5.0

data/docs/atlas_vector_search_guide.md

@@ -288,6 +288,85 @@ declared `dimensions:` before sending the pipeline. A mismatch raises
 it — callers get "expected 1536, got 768" instead of a server-side
 error after a round-trip.
 
+### Index drift verification (v5.5)
+
+On the first auto-discovered use of a vectorSearch index per
+(class, field, index) per process, the SDK compares the deployed
+index's `latestDefinition` against the model declaration:
+
+* `numDimensions` vs the property's declared `dimensions:` — a
+  mismatch means every query will be rejected or return nonsense
+  (usually an index that predates a model change).
+* `similarity` vs the property's declared `similarity:` (checked only
+  when both sides declare one).
+* When the class registers an `agent_tenant_scope`, the scope field
+  must appear among the index's `type: "filter"` paths — without it,
+  every tenant-scoped `$vectorSearch.filter` fails Atlas-side at
+  query time.
+
+Findings are computed once per (class, field, index) per process and
+governed by `Parse::VectorSearch.index_drift_policy`:
+
+```ruby
+Parse::VectorSearch.index_drift_policy = :warn   # default — [Parse::VectorSearch:DRIFT] warning on first check
+Parse::VectorSearch.index_drift_policy = :raise  # IndexDriftError on EVERY query against a drifted index
+Parse::VectorSearch.index_drift_policy = :ignore # skip verification
+```
+
+Under `:raise` the cached findings keep raising — strict mode means a
+drifted index never serves results, not "fails once, then passes".
+Auto-discovery verification costs no extra round-trip (the definition
+is already in hand from index discovery). An explicit `index:` kwarg
+is verified best-effort: when the catalog's covering index for the
+field carries the same name, its definition is checked too; catalog
+lookup failures never fail the query.
+
+### Query-embed caching and spend caps (v5.5)
+
+Every `text:`-overload query funnels through one embed path
+(`find_similar(text:)`, `hybrid_search(text:)`,
+`Parse::Retrieval.retrieve` all share it), which gives two controls:
+
+```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.
+Parse::Embeddings::Cache.enable!(max_entries: 2048, ttl: 600)
+Parse::Embeddings::Cache.stats   # => { enabled:, hits:, misses:, size: }
+
+# Per-tenant spend cap now covers DIRECT callers too, not just the
+# semantic_search agent tool. Tenant identity resolves to the ambient
+# Parse.with_cache_tenant scope when set, else a shared default bucket.
+# warn_at: adds a soft cap — crossing 80% of the limit emits a
+# parse.embeddings.spend_cap_warning AS::N event (alert, never refuse).
+Parse::Embeddings::SpendCap.configure(limit_tokens: 1_000_000, window: 3600,
+                                      warn_at: 0.8)
+Parse.with_cache_tenant("tenant_abc") do
+  Document.find_similar(text: query)   # charged against tenant_abc
+end
+```
+
+Cache hits emit the standard `parse.embeddings.embed` notification
+with `cached: true`, so existing spend subscribers see hits and misses
+on one stream. The cache is in-process by default; for a persistent
+layer shared across processes, wrap any Moneta-compatible backend in
+the bundled adapter:
+
+```ruby
+moneta = Moneta.new(:Redis, url: ENV["REDIS_URL"])
+Parse::Embeddings::Cache.enable!(
+  store: Parse::Embeddings::Cache::MonetaStore.new(moneta, ttl: 30 * 24 * 3600),
+)
+```
+
+`MonetaStore` namespaces keys, forwards TTL via Moneta's `expires:`,
+and fails open (a backend error is a cache miss, never a failed
+embed). Keys are input hashes — plaintext queries never land in the
+shared store; the VALUES are embeddings, so give the store the same
+access controls as the database. A query the agent tool already
+charged per-tenant is not double-billed (`SpendCap.with_precharged`
+wraps the tool's retrieval).
+
 ### ACL/CLP inheritance
 
 Vector search routes through `Parse::MongoDB.aggregate`. Every layer
@@ -405,6 +484,18 @@ branch — see [Hybrid search](#hybrid-search-vector--lexical) below) and
 chunking — see [Reranking](#reranking)). Both were reserved in earlier
 releases and now ship in 5.4.0.
 
+**Pointer values in filters translate automatically (v5.5).** A filter
+like `{ owner: some_user }` (a `Parse::Pointer` / `Parse::Object`, or a
+wire-form `{"__type" => "Pointer", ...}` hash — including inside `$in`
+/ `$eq` / `$ne` operator hashes) is rewritten to its MongoDB storage
+form `{ "_p_owner" => "_User$abc123" }` before the `$match` /
+`$vectorSearch.filter` is built, so pointer filters match rows instead
+of silently matching nothing. Translation runs after the
+underscore-key gate (callers still cannot name `_p_*` columns
+directly) and before the tenant-scope fold; the `semantic_search`
+agent tool inherits it. For `vector_filter:` use, the pointer column
+(`_p_owner`) must be declared `type: "filter"` in the index.
+
 ### Hybrid search (vector + lexical)
 
 `Class.hybrid_search` runs a lexical Atlas Search (`$search`) branch and a
@@ -556,13 +647,26 @@ envelope. See the [MCP guide's Token Economy section](./mcp_guide.md#token-econo
 
 ---
 
-## Image embedding: `embed_image` macro (v5.1)
+## Image embedding: `embed_image` macro (v5.1 URL mode, v5.5 bytes mode)
 
 `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`).
 
+Two fetch modes, selected per declaration with `source:`:
+
+* **`source: :url`** (default) — the SDK validates the file's URL and
+  forwards it; the **provider** performs the fetch from its own
+  network. Requires the `trust_provider_url_fetch` sentinel (see
+  operator setup below).
+* **`source: :bytes`** (v5.5) — the **SDK** downloads the image
+  through `Parse::File.safe_open_url`, verifies the content by
+  magic-byte sniff, strips EXIF/XMP metadata, and forwards the bytes
+  to the provider as a base64 data URI. No provider-side URL fetch
+  occurs, so the sentinel is NOT required — the
+  `allowed_image_hosts` allowlist still is.
+
 ```ruby
 class Post < Parse::Object
   property :cover_image,            :file
@@ -621,6 +725,57 @@ with `Parse::File`, not parallelized). Failures raise
 (`:scheme`, `:port`, `:userinfo`, `:host_blocked`,
 `:host_not_allowlisted`, `:parse`).
 
+### Bytes mode (`source: :bytes`, v5.5)
+
+```ruby
+# Operator setup — only the host allowlist is required (the sentinel
+# applies to URL forwarding, not SDK-side fetches):
+Parse::Embeddings.allowed_image_hosts = [".cloudfront.net"]
+
+class Post < Parse::Object
+  property :cover_image,           :file
+  property :cover_image_embedding, :vector,
+           dimensions: 1024, provider: :voyage, model: "voyage-multimodal-3"
+
+  embed_image :cover_image, into: :cover_image_embedding,
+              source: :bytes            # exif_strip: true is the default
+end
+```
+
+What happens on each (digest-miss) save:
+
+1. The file URL is validated through
+   `Parse::Embeddings.validate_image_url!(url, mode: :fetch)` — the
+   same host allowlist (deny-all when empty), obfuscated-IP screen,
+   port allowlist, and CIDR resolution check as URL mode, minus the
+   provider-egress sentinel.
+2. `Parse::File.safe_open_url` downloads the bytes — CIDR blocks,
+   DNS-rebinding re-check, port allowlist, `max_remote_size` cap,
+   timeouts. No parallel fetch mechanism exists.
+3. **Magic-byte verification** (`Parse::Embeddings::ImageFetch`):
+   the MIME type is determined exclusively from the leading bytes
+   (JPEG / PNG / GIF / WebP). The HTTP `Content-Type` header is never
+   consulted. The sniffed type must be in
+   `Parse::Embeddings.allowed_image_types` (default those four; SVG is
+   deliberately excluded as script-capable active content), and when
+   the URL carries a recognized image extension, the extension must
+   AGREE with the magic bytes — a `.jpg` URL serving PNG bytes (or
+   HTML) is refused as MIME laundering
+   (`ImageFetch::InvalidImageType`, with a `:reason` tag).
+4. **EXIF/XMP stripping, default ON.** JPEG APP1 segments (Exif and
+   XMP), PNG `eXIf` chunks, and WebP `EXIF`/`XMP ` RIFF chunks (with
+   the VP8X flag bits cleared) are removed before the bytes leave the
+   process — user photos commonly carry GPS coordinates and device
+   serials. Opt out per declaration with `exif_strip: false` when
+   orientation metadata must survive.
+5. The verified bytes ride to the provider as a base64 data URI
+   (Voyage `image_base64` content row; Cohere `image_url` data-URI
+   form).
+
+Direct provider calls accept the same shape:
+`provider.embed_image([Parse::Embeddings::ImageFetch.fetch!(url)])` —
+`FetchedImage` sources and URL Strings may be mixed in one batch.
+
 ### Save-side semantics
 
 * Digest is the **SHA-256 of the URL String**, not the file bytes.
@@ -641,24 +796,102 @@ with `Parse::File`, not parallelized). Failures raise
 
 ## Re-embedding existing rows
 
-Changing `model:`, `dimensions:`, or `provider:` on an existing
-`:vector` property is a migration regardless of whether the source is
-text or images. Workflow:
+### Provenance: the `<into>_meta` sibling (v5.5)
+
+Every `embed` / `embed_image` declaration auto-declares an
+`<into>_meta` `:object` sibling (override with `meta_field:`) stamped
+on each recompute and cleared with the vector:
+
+```ruby
+doc.body_embedding_meta
+# => { "provider"    => "openai",
+#      "model"       => "text-embedding-3-small",
+#      "dimensions"  => 1536,
+#      "modality"    => "text",
+#      "embedded_at" => "2026-06-09T17:32:11Z" }
+```
+
+This is the record migration tooling reads to know which model
+produced any stored vector.
+
+### Same-shape migrations: `Class.reembed!` (v5.5)
+
+When the new model has the **same dimensions** (e.g. swapping
+`text-embedding-3-small` for a same-width replacement, or a provider
+change at equal width), re-embed in place:
+
+```ruby
+# Re-embed every row through the CURRENT provider/model declaration.
+Document.reembed!(batch_size: 100)
+
+# Resumable: skip rows whose <into>_meta already matches the current
+# provider + model + dimensions (rows with no meta count as stale).
+Document.reembed!(only_stale: true)
+
+# Scope it
+Document.reembed!(field: :body_embedding, where: { published: true }, limit: 10_000)
+```
+
+`reembed!` walks the class with objectId-cursor pagination, clears
+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).
+
+### Changed-width migrations: dual-field workflow
+
+Changing `dimensions:` is a different beast — the existing
+vectorSearch index can't serve the new width. Use the shadow-field
+workflow:
 
 1. Add the new property alongside the old one
    (`property :body_embedding_v2, :vector, ...`) and an `embed` or
    `embed_image` block targeting it.
-2. Backfill: iterate existing rows, force a save (or null+save) to
-   trigger the new directive. The old field stays valid for reads.
-3. Once backfill completes, deploy a new vectorSearch index covering
-   the new field and migrate `find_similar` callers.
-4. Drop the old property.
-
-Do NOT mutate the model in place — the digest mechanism will see
-unchanged source text / unchanged source URL and skip recompute,
-leaving stale vectors. For `embed_image`, also remember the digest is
-over the URL String: if you replace bytes at the same URL (PUT-replace
-on S3 without renaming), null the digest field to force re-embed.
+2. Backfill with `embed_pending!(field: :body_embedding_v2)` — the new
+   field is null everywhere, so the null-filling walk is exactly right.
+3. Deploy a new vectorSearch index covering the new field and migrate
+   `find_similar` callers.
+4. Drop the old property and index.
+
+Do NOT mutate a model's `dimensions:` in place — the digest mechanism
+will see unchanged source text and skip recompute, leaving stale
+vectors, and the drift verifier will flag every query against the old
+index (`index numDimensions=1536 but property declares ...`). For
+`embed_image`, also remember the digest is over the URL String: if you
+replace bytes at the same URL (PUT-replace on S3 without renaming),
+null the digest field — or run `reembed!` — to force re-embed.
+
+---
+
+## Bulk embedding: `BatchEmbedder` (v5.5)
+
+`Provider#embed_text_batched` only slices input into provider-sized
+chunks; retry lives inside each provider's single HTTP call. For bulk
+jobs (ingest pipelines, chunk-corpus embedding) use
+`Parse::Embeddings::BatchEmbedder`, which adds batch-level pacing and
+backoff:
+
+```ruby
+embedder = Parse::Embeddings::BatchEmbedder.new(
+  Parse::Embeddings.provider(:openai),
+  requests_per_minute: 60,        # inter-batch pacing
+  max_attempts: 5,                # per-batch tries (exponential backoff + jitter)
+  on_progress: ->(done:, total:, batch_index:, batch_count:) {
+    puts "#{done}/#{total}"
+  },
+)
+vectors = embedder.embed_text(texts, input_type: :search_document)
+```
+
+Rate-limit and transient errors (any provider error class ending in
+`RateLimitError` / `TransientError`; override with `retry_on:`) retry
+with exponential backoff; other errors propagate immediately. A batch
+that exhausts its attempts raises `BatchEmbedder::BatchFailed`
+carrying `batch_index` and `completed_count`, so a resumable job knows
+exactly where to pick up.
 
 ---
 
@@ -728,6 +961,54 @@ floats out). Vectors only flow through the Parse↔Mongo path, where
 the body builder's `<vector dims=N>` compaction prevents them from
 landing in stdout / error trackers.
 
+### When the embedded source is PII: deployment checklist
+
+An embedding of PII is PII-equivalent. Inversion attacks reconstruct
+substantial source text from dense embeddings, and a vector's nearest
+neighbors leak the source's meaning even without reconstruction. If
+the fields you `embed` contain personal data (names, addresses, health
+or financial details, free-text user messages), treat the vector
+column with the same handling as the source column:
+
+1. **Provider contract.** You are sending the raw source text (and in
+   bytes mode, image content) to the embedding provider on every
+   recompute. Confirm the provider's data-retention and training-use
+   terms cover PII, and that a DPA is in place where required.
+   Self-hosting via `LocalHTTP` (Ollama / vLLM / TEI) keeps the text
+   in your network.
+2. **Keep vectors off the wire.** Leave `vector_visibility` at its
+   `:owner_only` default so vectors are omitted from `as_json` and
+   webhook payloads. Do not flip a PII class to `:public`.
+3. **Row ACL still governs.** Vector hits route mongo-direct with
+   `_rperm` enforcement — verify your rows carry real ACLs and that
+   callers use scoped credentials (`session_token:` / `acl_user:`),
+   not blanket master key.
+4. **Tenant isolation.** Multi-tenant deployments must declare
+   `agent_tenant_scope` on searchable classes; the scope folds into
+   `$vectorSearch.filter` (and v5.5's drift verification confirms the
+   index covers it). Without it, similarity scores leak cross-tenant
+   document existence.
+5. **Score exposure.** Keep score quantization on for non-admin agent
+   contexts (the default) — full-precision scores enable
+   membership-inference probing.
+6. **EXIF stays stripped.** For image embedding, keep the bytes-mode
+   default `exif_strip: true`; user photos carry GPS coordinates and
+   device serials that would otherwise reach the provider.
+7. **Log and cache hygiene.** Redact query text at the Faraday layer
+   (above); if you enable the persistent L2 cache, note that cache
+   KEYS are hashes (no plaintext) but cache VALUES are the embeddings
+   themselves — point `MonetaStore` at a store with the same access
+   controls as the database.
+8. **Deletion propagation.** When a user exercises erasure rights,
+   the vector, its `<field>_digest`, and its `<field>_meta` siblings
+   live on the same row and delete with it — but check external
+   copies: provider-side logs (their retention policy), your L2
+   embedding cache (TTL or explicit flush), and any analytics sink
+   subscribed to embedding events.
+9. **Migration hygiene.** `reembed!` re-sends every row's source text
+   to the provider — schedule PII-class migrations under the same
+   approvals as a data export.
+
 ---
 
 ## Troubleshooting
@@ -775,10 +1056,20 @@ on every poll) rather than a `until index_ready?; sleep` loop.
 Key files:
 
 * `lib/parse/embeddings.rb` — registry, `Configuration`, `register`,
-  `provider`, `configure`, `validate_image_url!`,
-  `trust_provider_url_fetch=`, `allowed_image_hosts=`.
+  `provider`, `configure`, `validate_image_url!` (`mode: :forward | :fetch`),
+  `trust_provider_url_fetch=`, `allowed_image_hosts=`,
+  `allowed_image_types=`.
 * `lib/parse/embeddings/provider.rb` — abstract base, `validate_response!`,
   `instrument_embed`, AS::N payload contract.
+* `lib/parse/embeddings/image_fetch.rb` — bytes-fetch path:
+  `ImageFetch.fetch!`, magic-byte `sniff_mime`/`verify!`, EXIF/XMP
+  stripping, `FetchedImage`.
+* `lib/parse/embeddings/batch_embedder.rb` — `BatchEmbedder` bulk
+  orchestration (pacing, batch-level backoff, `BatchFailed`).
+* `lib/parse/embeddings/cache.rb` — opt-in query-embed cache
+  (`Cache.enable!` / `fetch_vector` / `stats`).
+* `lib/parse/embeddings/spend_cap.rb` — per-tenant token cap
+  (`charge!`, `charge_query!`, `with_precharged`).
 * `lib/parse/embeddings/openai.rb` — OpenAI provider.
 * `lib/parse/embeddings/cohere.rb` — Cohere v3 + v4.0 text-mode provider.
 * `lib/parse/embeddings/voyage.rb` — Voyage text + multimodal-3
@@ -788,9 +1079,13 @@ Key files:
 * `lib/parse/embeddings/local_http.rb` — generic OpenAI-compatible
   local-gateway client.
 * `lib/parse/embeddings/fixture.rb` — deterministic test provider.
-* `lib/parse/model/core/vector_searchable.rb` — `find_similar`.
+* `lib/parse/model/core/vector_searchable.rb` — `find_similar`,
+  `hybrid_search`, index drift verification
+  (`Parse::VectorSearch.index_drift_policy`).
 * `lib/parse/model/core/embed_managed.rb` — `embed` and `embed_image`
-  macros, `EmbedDirective` (carries `modality:`, `allow_insecure:`).
+  macros, `EmbedDirective` (carries `modality:`, `allow_insecure:`,
+  `source_mode:`, `exif_strip:`, `meta_field:`), `embed_pending!`,
+  `reembed!`.
 * `lib/parse/vector_search.rb` — low-level `Parse::VectorSearch.search`.
 * `lib/parse/atlas_search/index_manager.rb` — `IndexCatalog.create_index`,
   `find_vector_index`, `wait_for_ready`.

data/lib/parse/api/users.rb

@@ -223,15 +223,25 @@ module Parse
       # - code 205 (+ERROR_EMAIL_NOT_FOUND+) when +preventLoginWithUnverifiedEmail+
       #   is enabled and the account's email has not been verified.
       #
+      # Client-side rate limited per username using the SAME bucket as {#login}
+      # (bare username, no namespace) — failures across both credential oracles
+      # accumulate, so an attacker cannot bypass a +login+ lockout by pivoting to
+      # this endpoint. The trade-off: a run of failed step-up re-auth calls counts
+      # toward (and can trigger) the primary login lockout for that username.
+      # Client-side limiting is a convenience, not a boundary — the server is the
+      # real control.
+      #
       # @param username [String] the Parse user username.
       # @param password [String] the Parse user's associated password.
       # @param headers [Hash] additional HTTP headers to send with the request.
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @return [Parse::Response]
       def verify_password(username, password, headers: {}, **opts)
+        check_login_rate_limit!(username)
         body = { username: username, password: password }
         response = request :post, VERIFY_PASSWORD_PATH, body: body, headers: headers, opts: opts
         response.parse_class = Parse::Model::CLASS_USER
+        track_login_attempt(username, response.success?)
         response
       end
 

data/lib/parse/client.rb

@@ -1425,6 +1425,22 @@ module Parse
   # Object/Pointer envelope is converted, and an Object of an UNregistered class
   # is left as a raw Hash (building it would degrade to a field-less Pointer).
   # Plain Hashes and arbitrary `__type` app data pass through untouched.
+  #
+  # SECURITY — cloud results are treated as server-authoritative. The
+  # `__type:"Object"` decode in {._decode_cloud_value} routes through
+  # +Parse::Object.build+, which hydrates with trusted-init — the SAME path
+  # used to decode every query / +.fetch+ result. Trusted-init skips the
+  # +PROTECTED_INITIALIZE_KEYS+ filter, so credential-shaped keys
+  # (+sessionToken+, +authData+, +_rperm+, +_wperm+, +roles+, …) present in a
+  # cloud function's return value populate the in-memory object, exactly as they
+  # do for any other server response. This is by design: the payload is authored
+  # by your Cloud Code and the request is caller-authenticated, and making cloud
+  # results filter these keys would make them inconsistent with (and stricter
+  # than) query/+.fetch+ hydration — e.g. a cloud function returning
+  # +request.user+ would come back missing its +sessionToken+. If a cloud
+  # function is expected to echo back third-party-influenced data, call it with
+  # +raw: true+ (+Parse.call_function(name, body, raw: true)+) to receive the
+  # undecoded response and sanitize it yourself before building objects.
   def self._extract_cloud_result(response)
     r = response.result
     value = r.is_a?(Hash) ? r["result"] : r
@@ -1568,7 +1584,9 @@ module Parse
   # specific {Parse::Error} subclasses as the underlying client does.
   # @param name (see Parse.call_function)
   # @param body (see Parse.call_function)
-  # @param opts (see Parse.call_function) — :raw is ignored.
+  # @param opts (see Parse.call_function) — +:raw+ has no effect; this method
+  #   always decodes the result. Use {Parse.call_function} with +raw: true+ if
+  #   you need the undecoded response.
   # @raise [Parse::Error::CloudCodeError] when the response indicates a cloud-code error.
   # @return [Object] the result data of the response.
   def self.call_function!(name, body = {}, **opts)

data/lib/parse/embeddings/batch_embedder.rb

@@ -0,0 +1,188 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module Embeddings
+    # Batch-level orchestration for bulk embedding jobs.
+    #
+    # {Provider#embed_text_batched} only slices input into
+    # provider-sized chunks; any retry/backoff lives inside each
+    # provider's single HTTP call. That is the wrong layer for bulk
+    # work: a 50k-document backfill needs *batch-level* pacing (stay
+    # under the provider's requests-per-minute budget across calls) and
+    # *batch-level* backoff (a 429 after the provider's internal retries
+    # are exhausted should pause the whole job, not kill it).
+    # {BatchEmbedder} wraps any registered provider with both.
+    #
+    # @example Backfill with pacing and backoff
+    #   embedder = Parse::Embeddings::BatchEmbedder.new(
+    #     Parse::Embeddings.provider(:openai),
+    #     requests_per_minute: 60,
+    #     max_attempts: 5,
+    #   )
+    #   vectors = embedder.embed_text(texts, input_type: :search_document)
+    #
+    # @example Progress reporting
+    #   embedder = Parse::Embeddings::BatchEmbedder.new(provider,
+    #     on_progress: ->(done:, total:, batch_index:, batch_count:) {
+    #       puts "#{done}/#{total}"
+    #     })
+    #
+    # == Retry classification
+    #
+    # By default a batch is retried when the provider raises a
+    # {Parse::Embeddings::Error} subclass whose class name ends in
+    # `RateLimitError` or `TransientError` — the convention every
+    # bundled provider follows (`OpenAI::RateLimitError`,
+    # `Voyage::TransientError`, …). Pass `retry_on:` with explicit
+    # exception classes to override. Non-retryable errors (auth,
+    # bad-request, response-contract violations) propagate immediately.
+    #
+    # Vectors are returned aligned 1:1 with the input, identical to
+    # `embed_text` on the wrapped provider.
+    class BatchEmbedder
+      # Raised when a batch still fails after `max_attempts` retryable
+      # failures. Wraps the final provider error in `#cause` and carries
+      # the index of the failing batch so a resumable job knows where to
+      # pick up.
+      class BatchFailed < Parse::Embeddings::Error
+        # @return [Integer] zero-based index of the failing batch.
+        attr_reader :batch_index
+        # @return [Integer] number of inputs successfully embedded before the failure.
+        attr_reader :completed_count
+
+        def initialize(message, batch_index:, completed_count:)
+          @batch_index = batch_index
+          @completed_count = completed_count
+          super(message)
+        end
+      end
+
+      RETRYABLE_NAME_SUFFIXES = %w[RateLimitError TransientError].freeze
+
+      # @return [Provider] the wrapped provider.
+      attr_reader :provider
+
+      # @param provider [Provider] any registered embedding provider.
+      # @param batch_size [Integer, nil] inputs per provider call.
+      #   Defaults to the provider's own {Provider#embed_batch_size}
+      #   hint, falling back to 64 when the provider has none.
+      # @param requests_per_minute [Numeric, nil] batch-level pacing
+      #   budget. When set, consecutive provider calls are spaced at
+      #   least `60.0 / requests_per_minute` seconds apart. nil disables
+      #   pacing.
+      # @param max_attempts [Integer] attempts per batch (1 = no retry).
+      # @param base_delay [Numeric] first backoff delay in seconds;
+      #   doubles per attempt.
+      # @param max_delay [Numeric] backoff ceiling in seconds.
+      # @param jitter [Numeric] random multiplier range added to each
+      #   delay (`delay * (1 + rand * jitter)`); spreads thundering
+      #   herds when several workers back off together.
+      # @param retry_on [Array<Class>, nil] explicit retryable exception
+      #   classes; nil uses the name-suffix convention described above.
+      # @param on_progress [#call, nil] callable invoked after each
+      #   successful batch with `done:, total:, batch_index:, batch_count:`.
+      def initialize(provider, batch_size: nil, requests_per_minute: nil,
+                     max_attempts: 5, base_delay: 2.0, max_delay: 60.0,
+                     jitter: 0.25, retry_on: nil, on_progress: nil)
+        unless provider.is_a?(Provider)
+          raise ArgumentError,
+                "Parse::Embeddings::BatchEmbedder expects a Parse::Embeddings::Provider " \
+                "(got #{provider.class})."
+        end
+        @provider = provider
+        @batch_size = batch_size ? Integer(batch_size) : nil
+        raise ArgumentError, "batch_size must be positive" if @batch_size && @batch_size <= 0
+        @min_interval = requests_per_minute ? (60.0 / Float(requests_per_minute)) : nil
+        @max_attempts = Integer(max_attempts)
+        raise ArgumentError, "max_attempts must be >= 1" if @max_attempts < 1
+        @base_delay = Float(base_delay)
+        @max_delay = Float(max_delay)
+        @jitter = Float(jitter)
+        @retry_on = retry_on && Array(retry_on)
+        @on_progress = on_progress
+        @last_call_at = nil
+      end
+
+      # Embed `strings` through the wrapped provider with pacing and
+      # batch-level backoff.
+      #
+      # @param strings [Array<String>]
+      # @param input_type [Symbol]
+      # @return [Array<Array<Float>>] aligned 1:1 with `strings`.
+      # @raise [BatchFailed] when a batch exhausts its attempts.
+      def embed_text(strings, input_type: :search_document)
+        unless strings.is_a?(Array)
+          raise ArgumentError,
+                "Parse::Embeddings::BatchEmbedder#embed_text expects Array<String> " \
+                "(got #{strings.class})."
+        end
+        return [] if strings.empty?
+
+        size = @batch_size || @provider.embed_batch_size || 64
+        batches = strings.each_slice(size).to_a
+        out = []
+        batches.each_with_index do |batch, idx|
+          out.concat(run_batch(batch, input_type, idx, out.length))
+          if @on_progress
+            @on_progress.call(done: out.length, total: strings.length,
+                              batch_index: idx, batch_count: batches.length)
+          end
+        end
+        out
+      end
+
+      private
+
+      def run_batch(batch, input_type, batch_index, completed_count)
+        attempts = 0
+        begin
+          attempts += 1
+          pace!
+          @provider.embed_text(batch, input_type: input_type)
+        rescue StandardError => e
+          raise unless retryable?(e)
+          if attempts >= @max_attempts
+            raise BatchFailed.new(
+              "Parse::Embeddings::BatchEmbedder: batch #{batch_index} failed after " \
+              "#{attempts} attempt(s) — #{e.class}: #{e.message}",
+              batch_index: batch_index, completed_count: completed_count,
+            )
+          end
+          sleep(backoff_delay(attempts))
+          retry
+        end
+      end
+
+      def retryable?(error)
+        if @retry_on
+          return @retry_on.any? { |klass| error.is_a?(klass) }
+        end
+        return false unless error.is_a?(Parse::Embeddings::Error)
+        name = error.class.name.to_s
+        RETRYABLE_NAME_SUFFIXES.any? { |suffix| name.end_with?(suffix) }
+      end
+
+      def backoff_delay(attempt)
+        delay = [@base_delay * (2**(attempt - 1)), @max_delay].min
+        delay * (1.0 + rand * @jitter)
+      end
+
+      # Enforce the inter-call interval. Measured from the START of the
+      # previous call so a slow provider response counts toward the
+      # interval rather than stacking on top of it.
+      def pace!
+        return if @min_interval.nil?
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        if @last_call_at
+          wait = (@last_call_at + @min_interval) - now
+          if wait > 0
+            sleep(wait)
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          end
+        end
+        @last_call_at = now
+      end
+    end
+  end
+end