solid_queue-coalesce 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9832b3432d9f235ba2e8b752017633b5bd974f26277ed30eae8e72651a942cf7
-  data.tar.gz: 4b74f5be0748dbd2e47d8489fb984b836de4de0d0621710b559e12f7bd98290e
+  metadata.gz: 74e791e65276dd0da04b025f1d6e545958eda7f4c09e6ecc6e7babb1450c9af6
+  data.tar.gz: c3bb125145fe32176a8c68f38ca3abbf6dad27945b4784c96a5d841a84a6f234
 SHA512:
-  metadata.gz: 568cd5b18e36ac02fae073249b54e98546bdca672ecd08bb6db130eb936b5ae47da721e5123067fdee7d6240ef12ae082780c63aeeadab2ea835afe3407cbe7a
-  data.tar.gz: 0c160c406c984cae3e303c9dcef834f21ae95658fd1456fccb5a57be5c42dcd1d7aae650e1d7ad60c3a402d565c8b7cab8851d674324402bc4c28fff2390f20a
+  metadata.gz: f018f79efb38543b7cd6f2cde3b728a9f1d03a7d8197af28371280f9ecf51e6adef3cb3e47ac37aaabb5cf86a6cdd8d1a824420e864177be6879f8f1950ca255
+  data.tar.gz: a931e752c3b9a6308b0f1637c2b88f36d5460140be05c3db2925acd00959b612a93352103d2418bc2c7ba52b68cfb8466d8f46749ba83d42fb841dfbc791d25c

data/CHANGELOG.md

@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-11-06
+
+Adds `on_conflict: :replace`, which runs a pending job with its latest call's arguments, and a recipe that combines it with `limits_concurrency` and [Solid Queue Rate Limit](https://github.com/dtcristo/solid_queue-rate_limit). Aligns key declarations and bulk enqueue errors with upstream Solid Queue, and prefixes the serialized coalescing marker with `solid_queue_`. Batch coalescing keys also use the shorter `Batch/` prefix. Upgrading takes work: drain coalesced jobs and affected batches, retry or discard failed jobs on the old version, and deploy all processes together; see [UPGRADING.md](https://github.com/dtcristo/solid_queue-coalesce/blob/main/UPGRADING.md).
+
+### Added
+
+- `on_conflict: :replace` for `coalesce`. A call writes its arguments over the pending job's, which keeps its ID, queue, priority and place in line, and runs `perform` with the latest ones. It reports `:replaced`, works with `debounce:`, `max_wait:`, blocking concurrency limits and batches, and can't be used by a recurring task. ([#47](https://github.com/dtcristo/solid_queue-coalesce/pull/47))
+- README recipe that syncs the latest state one at a time under an API quota, combining `coalesce` with `limits_concurrency` and [Solid Queue Rate Limit](https://github.com/dtcristo/solid_queue-rate_limit) 0.2, with a table of which control acts at each step. ([#53](https://github.com/dtcristo/solid_queue-coalesce/pull/53))
+
+### Changed
+
+- A replacement keeps the pending job's [Solid Queue Rate Limit](https://github.com/dtcristo/solid_queue-rate_limit) key, as it keeps its concurrency key, so the job is charged to the budget of the call that created it. ([#53](https://github.com/dtcristo/solid_queue-coalesce/pull/53))
+- **Breaking:** Serialized job data uses `solid_queue_coalesce_on_conflict` instead of `coalesce_on_conflict`, with no fallback. Drain all coalesced work, including retrying or discarding failures, before deploying. ([#46](https://github.com/dtcristo/solid_queue-coalesce/pull/46))
+- **Breaking:** `coalesce(key:)` accepts declarations without type or blank validation, like `limits_concurrency`. Unsupported truthy types produce a class-wide key, blank declarations coalesce, and `nil` or `false` disables coalescing. Other options retain their validation. ([#46](https://github.com/dtcristo/solid_queue-coalesce/pull/46))
+- **Breaking:** Bulk enqueues propagate original Active Record errors for coalesced jobs, like native bulk enqueue. Single enqueues retain `SolidQueue::Job::EnqueueError`; notification subscriber errors remain unwrapped. ([#46](https://github.com/dtcristo/solid_queue-coalesce/pull/46))
+- **Breaking:** Batched coalescing keys start with `Batch/<id>/` instead of `SolidQueue::Batch/<id>/`, including keys in `coalesce.solid_queue` notifications. Drain affected batches before upgrading so new calls don't create separate jobs under the new keys. ([#43](https://github.com/dtcristo/solid_queue-coalesce/pull/43))
+- CI tests each Solid Queue 1.7 release and Solid Queue main, and runs each Ruby with one Rails instead of with every Rails. ([#54](https://github.com/dtcristo/solid_queue-coalesce/pull/54))
+
+
 ## [0.2.0] - 2026-11-02
 
 Adds debouncing with `debounce:` and `max_wait:`, batches that run as soon as they fill with `on_full: :dispatch`, and support for [`SolidQueue::Batch`](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#batch-jobs). Collecting jobs now use `perform_calls(calls)`, so upgrading from 0.1.0 needs code changes, a drain and a migration. See [UPGRADING.md](https://github.com/dtcristo/solid_queue-coalesce/blob/main/UPGRADING.md).
@@ -59,6 +78,7 @@ The first release lets many `perform_later` calls with the same key share one pe
 - The `coalesce.solid_queue` and `drop_coalesced_argument.solid_queue` notifications. ([#1](https://github.com/dtcristo/solid_queue-coalesce/pull/1))
 - Requires Solid Queue 1.7. ([#1](https://github.com/dtcristo/solid_queue-coalesce/pull/1))
 
-[Unreleased]: https://github.com/dtcristo/solid_queue-coalesce/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/dtcristo/solid_queue-coalesce/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/dtcristo/solid_queue-coalesce/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/dtcristo/solid_queue-coalesce/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/dtcristo/solid_queue-coalesce/releases/tag/v0.1.0

data/README.md

@@ -1,10 +1,69 @@
-# Solid Queue Coalesce
+<div align="center">
+  <h1>Solid Queue Coalesce</h1>
+  <p>
+    <strong>Dedupe, debounce and batch <a href="https://github.com/rails/solid_queue">Solid Queue</a> jobs</strong>
+  </p>
+</div>
 
-Dedupe, debounce and batch [Solid Queue](https://github.com/rails/solid_queue) jobs. Many `perform_later` calls with the same key share one pending job, and that key is held only until the job starts. A call that arrives after that opens a new job, so anything that happens after a run has started is always covered by another run.
+Solid Queue Coalesce merges repeated `perform_later` calls with the same key into one job. You choose whether that job runs with the first call, the latest one, or all of them.
 
-It isn't strict uniqueness. A job can run again for each new call after the last run started, and two runs can overlap. Use [`limits_concurrency`](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#concurrency-controls) alongside it to stop overlaps, and see [`coalesce` or `limits_concurrency`?](#coalesce-or-limits_concurrency) to choose.
+Dedupe when a repeat call adds nothing:
 
-It's a separate gem that adds to Solid Queue from the outside, with its own tables. It only works with the Solid Queue adapter, because a foreign key to the job and a shared transaction are what let it work without a time window to configure.
+```ruby
+class ReindexProductJob < ApplicationJob
+  coalesce key: ->(product_id) { product_id }
+
+  def perform(product_id)
+    Product.find(product_id).reindex!
+  end
+end
+
+ReindexProductJob.perform_later(product.id)
+```
+
+Replace when each call carries the whole current state, and only the latest matters:
+
+```ruby
+class SyncContactJob < ApplicationJob
+  coalesce key: ->(user_id, *) { user_id }, on_conflict: :replace, debounce: 10.seconds
+
+  def perform(user_id, attributes)
+    Crm.update_contact(user_id, attributes)
+  end
+end
+
+SyncContactJob.perform_later(user.id, user.slice(:name, :email))
+```
+
+Collect when every call carries data you need. The `wait` gives calls time to join:
+
+```ruby
+class BulkReindexProductsJob < ApplicationJob
+  coalesce key: ->(account_id, *) { account_id }, on_conflict: :collect
+
+  def perform_calls(calls)
+    product_ids = calls.map { |call| call.arguments.last }.uniq
+    SearchIndex.bulk_index(Product.where(id: product_ids))
+  end
+end
+
+BulkReindexProductsJob.set(wait: 30.seconds).perform_later(product.account_id, product.id)
+```
+
+A job accepts calls until it starts. A collecting job also stops at `max_calls`, 100 by default. A call after that opens a new job, so no change gets missed, but two runs can overlap. Add [`limits_concurrency`](#coalesce-or-limits_concurrency) to stop that.
+
+To limit how fast the coalesced jobs run, pair it with [Solid Queue Rate Limit](https://github.com/dtcristo/solid_queue-rate_limit). The [last recipe](#sync-the-latest-state-one-at-a-time-under-an-api-quota) uses both.
+
+## Features
+
+- [Dedupe](#dedupe-jobs-with-one-pending-job-per-key). Calls with the same key share one pending job, which runs with the first call's arguments.
+- [Replace](#run-with-the-latest-arguments). One pending job runs `perform` with the latest call's arguments.
+- [Collect](#collect-calls-into-one-run). One job receives every call's arguments, for bulk APIs and digests.
+- [Debounce](#debounce-until-activity-stops). A job waits until calls stop, with an optional deadline.
+- [Throttle](#throttle-to-one-run-per-window). A key runs at most once per time window.
+- [Run on the leading edge](#run-on-the-leading-edge). The first call runs right away, and calls during that run merge into one follow-up.
+
+It also works with [recurring tasks](#coalesce-a-recurring-task), [bulk enqueues](#bulk-enqueues) and [Solid Queue batches](#solid-queue-batches).
 
 ## Table of contents
 
@@ -15,6 +74,7 @@ It's a separate gem that adds to Solid Queue from the outside, with its own tabl
 - [Compatibility](#compatibility)
 - [`coalesce` options](#coalesce-options)
 - [Keys](#keys)
+- [Replacing arguments](#replacing-arguments)
 - [Collecting calls](#collecting-calls)
 - [Collecting jobs and scheduling](#collecting-jobs-and-scheduling)
 - [Debouncing](#debouncing)
@@ -47,21 +107,7 @@ bin/rails generate solid_queue:coalesce:install
 bin/rails db:migrate
 ```
 
-Add `coalesce` to a job, with a [key](#keys) that says which calls belong together:
-
-```ruby
-class ReindexProductJob < ApplicationJob
-  coalesce key: ->(product_id) { product_id }
-
-  def perform(product_id)
-    Product.find(product_id).reindex!
-  end
-end
-
-ReindexProductJob.perform_later(product.id)
-```
-
-The first call creates a job. Later calls with that key get discarded until the job starts. Pick a [recipe](#recipes) for anything more specific.
+Add `coalesce` to a job, with a [key](#keys) that says which calls belong together, then pick a [recipe](#recipes).
 
 ### Where the migration goes
 
@@ -85,28 +131,35 @@ To upgrade from an earlier version, follow [UPGRADING.md](UPGRADING.md). [CHANGE
 
 Start from what you want to happen to a burst of calls.
 
-Run once, with the first call's arguments:
+Dedupe, so one run gets the first call's arguments:
 
 - [As soon as a worker is free](#dedupe-jobs-with-one-pending-job-per-key)
 - [At most once per time window](#throttle-to-one-run-per-window)
 - [Once calls stop, or by a deadline](#debounce-until-activity-stops)
 - [Now, then once more after the run](#run-on-the-leading-edge)
 - [On a schedule, without piling up](#coalesce-a-recurring-task)
-- [With a callback once a group of jobs is done](#dedupe-jobs-in-a-solid-queue-batch)
 
-Run once, with every call's arguments:
+Replace, so one run gets the latest call's arguments:
+
+- [Once calls stop](#run-with-the-latest-arguments)
 
-- [After a fixed time](#batch-calls-together)
-- [At N calls or T seconds](#run-a-batch-at-n-calls-or-t-seconds)
-- [Once calls stop, or at N calls](#debounce-a-batch)
-- [At midnight](#run-a-batch-at-midnight)
-- [One batch at a time](#run-one-batch-at-a-time)
-- [Resuming after a deploy](#resume-a-long-batch)
+Collect, so one run gets every call's arguments:
+
+- [After a fixed time](#collect-calls-into-one-run)
+- [At N calls or T seconds](#collect-until-n-calls-or-t-seconds)
+- [Once calls stop, or at N calls](#collect-until-calls-stop)
+- [At midnight](#collect-calls-until-midnight)
+- [One job at a time](#run-one-collecting-job-at-a-time)
+- [Resuming after a deploy](#resume-a-long-collecting-job)
 
 Run every call:
 
 - [One at a time, without `coalesce`](#run-every-call-one-at-a-time)
 
+Under an API's quota:
+
+- [The latest state, one at a time for each key](#sync-the-latest-state-one-at-a-time-under-an-api-quota)
+
 `Product`, `SearchIndex` and the other names in these recipes stand in for your own code.
 
 ### Dedupe jobs with one pending job per key
@@ -188,37 +241,27 @@ production:
     schedule: every minute
 ```
 
-A tick during a run creates one blocked job, later ticks merge into it, and it runs when the current run finishes. Without `limits_concurrency`, a slow run can overlap the next tick's. A recurring task can't use `:collect` or `debounce:`. See [Recurring jobs and concurrency limits](#recurring-jobs-and-concurrency-limits).
+A tick during a run creates one blocked job, later ticks merge into it, and it runs when the current run finishes. Without `limits_concurrency`, a slow run can overlap the next tick's. A recurring task can't use `:replace`, `:collect` or `debounce:`. See [Recurring jobs and concurrency limits](#recurring-jobs-and-concurrency-limits).
 
-### Dedupe jobs in a Solid Queue batch
+### Run with the latest arguments
 
-Use this when a callback should run once a group of jobs is done, and jobs in that group can ask for the same work.
+Use this when each call carries the whole current state, such as a contact to sync, and older calls are out of date.
 
 ```ruby
-class ReindexProductJob < ApplicationJob
-  coalesce key: ->(product_id) { product_id }
+class SyncContactJob < ApplicationJob
+  coalesce key: ->(user_id, *) { user_id }, on_conflict: :replace, debounce: 10.seconds
 
-  def perform(product_id)
-    Product.find(product_id).reindex!
-  end
-end
-
-class ImportSupplierJob < ApplicationJob
-  def perform(supplier_id)
-    Supplier.find(supplier_id).import_products.each do |product_id|
-      batch.enqueue { ReindexProductJob.perform_later(product_id) }
-    end
+  def perform(user_id, attributes)
+    Crm.update_contact(user_id, attributes)
   end
 end
 
-SolidQueue::Batch.enqueue(on_success: PublishCatalogJob) do
-  supplier_ids.each { |supplier_id| ImportSupplierJob.perform_later(supplier_id) }
-end
+SyncContactJob.perform_later(user.id, user.slice(:name, :email))
 ```
 
-Each importer adds to the batch while it runs, and that running job keeps the batch open. Two importers that reach the same pending product share one reindex. If that reindex has already started, the later call opens a new job, so the later change still gets reindexed. `PublishCatalogJob` runs once, after the importers and every reindex are done. See [Solid Queue batches](#solid-queue-batches).
+The job runs 10 seconds after the last call, with that call's arguments. Each call replaces the pending job's arguments, and the job keeps its ID, queue, priority and place in line. A call after the job starts opens the next one. If `perform` can read the current state from an ID, use the default `:discard` instead. See [Replacing arguments](#replacing-arguments).
 
-### Batch calls together
+### Collect calls into one run
 
 Use this when every call carries data you need, and one run should process them.
 
@@ -235,17 +278,17 @@ end
 BulkReindexProductsJob.set(wait: 30.seconds).perform_later(product.account_id, product.id)
 ```
 
-`max_calls` is the most calls one run takes, 100 if you don't set it. A full job still waits for its time, and the next call opens a new job. A plain `perform_later` that arrives first opens a job that runs right away, and the batch is as small as what got there in time. A retry runs all of the job's calls again, so `perform_calls` has to be idempotent. See [Collecting calls](#collecting-calls), [Collecting jobs and scheduling](#collecting-jobs-and-scheduling) and [Retries](#retries).
+`max_calls` is the most calls one run takes, 100 if you don't set it. A full job still waits for its time, and the next call opens a new job. A plain `perform_later` that arrives first opens a job that runs right away, and the run only gets the calls that arrived in time. A retry runs all of the job's calls again, so `perform_calls` has to be idempotent. See [Collecting calls](#collecting-calls), [Collecting jobs and scheduling](#collecting-jobs-and-scheduling) and [Retries](#retries).
 
-### Run a batch at N calls or T seconds
+### Collect until N calls or T seconds
 
-Use this when a batch should run as soon as it's full, and a quiet key still shouldn't wait forever.
+Use this when a collecting job should run as soon as it's full, and a quiet key still shouldn't wait forever.
 
 ```ruby
 class BulkReindexProductsJob < ApplicationJob
   coalesce key: ->(account_id, *) { account_id }, on_conflict: :collect, max_calls: 100, on_full: :dispatch
 
-  # perform_calls as in the batch recipe
+  # perform_calls as in the collect recipe
 end
 
 BulkReindexProductsJob.set(wait: 30.seconds).perform_later(product.account_id, product.id)
@@ -253,9 +296,9 @@ BulkReindexProductsJob.set(wait: 30.seconds).perform_later(product.account_id, p
 
 The `wait` is the T. A plain `perform_later` that arrives first runs right away, and so doesn't wait for N. See [Collecting jobs and scheduling](#collecting-jobs-and-scheduling) and the [timeline](#scheduling-timelines).
 
-### Debounce a batch
+### Collect until calls stop
 
-Use this when a batch should run when it's quiet, when it's full or at the cap, whichever comes first.
+Use this when a collecting job should run when it's quiet, when it's full or at the cap, whichever comes first.
 
 ```ruby
 class BulkReindexProductsJob < ApplicationJob
@@ -266,7 +309,7 @@ class BulkReindexProductsJob < ApplicationJob
            debounce: 30.seconds,
            max_wait: 5.minutes
 
-  # perform_calls as in the batch recipe
+  # perform_calls as in the collect recipe
 end
 
 BulkReindexProductsJob.perform_later(product.account_id, product.id)
@@ -274,7 +317,7 @@ BulkReindexProductsJob.perform_later(product.account_id, product.id)
 
 See [Debouncing](#debouncing).
 
-### Run a batch at midnight
+### Collect calls until midnight
 
 Use this when calls collect through the day, and all of the work should happen overnight.
 
@@ -292,26 +335,26 @@ SendDailyDigestJob.set(wait_until: Date.tomorrow.midnight).perform_later(account
 
 The first call sets the time, and later calls join without moving it. Past `max_calls`, the next call opens another job for the same midnight, and the two can overlap. A call that arrives after midnight joins a job that hasn't started yet, and otherwise opens tomorrow's. Every caller needs the `wait_until`, because a plain `perform_later` that arrives first opens a job that runs right away. Payloads wait in the queue database all day, so pass IDs.
 
-### Run one batch at a time
+### Run one collecting job at a time
 
-Use this when batches for a key shouldn't overlap, such as writes to one account's records.
+Use this when a key's collecting jobs shouldn't overlap, such as writes to one account's records.
 
 ```ruby
 class BulkReindexProductsJob < ApplicationJob
   coalesce key: ->(account_id, *) { account_id }, on_conflict: :collect, max_calls: 100
   limits_concurrency to: 1, key: ->(account_id, *) { account_id }, on_conflict: :block, duration: 15.minutes
 
-  # perform_calls as in the batch recipe
+  # perform_calls as in the collect recipe
 end
 
 BulkReindexProductsJob.perform_later(product.account_id, product.id)
 ```
 
-The second batch blocks until the first finishes, and keeps collecting until it starts. See [Recurring jobs and concurrency limits](#recurring-jobs-and-concurrency-limits).
+The second job blocks until the first finishes, and keeps collecting until it starts. See [Recurring jobs and concurrency limits](#recurring-jobs-and-concurrency-limits).
 
-### Resume a long batch
+### Resume a long collecting job
 
-Use this when a batch can outlast a worker's shutdown, and repeating it is expensive, such as with a paid or rate-limited bulk API. It needs Rails 8.1.
+Use this when a collecting job can outlast a worker's shutdown, and repeating it is expensive, such as with a paid or rate-limited bulk API. It needs Rails 8.1.
 
 ```ruby
 class EmbedDocumentsJob < ApplicationJob
@@ -354,6 +397,37 @@ ApplyLedgerEntryJob.perform_later(account.id, entry.id)
 
 Each call creates its own job, and they wait their turn. See Solid Queue's [concurrency controls](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#concurrency-controls).
 
+### Sync the latest state one at a time, under an API quota
+
+Use this when each call carries a contact's whole current state, two syncs for one contact mustn't overlap, and all syncs together have to stay under the CRM's quota. It needs [Solid Queue Rate Limit](https://github.com/dtcristo/solid_queue-rate_limit).
+
+```ruby
+class SyncContactJob < ApplicationJob
+  # One pending and one running sync for each user, and at most 2 claims in any second across them
+  coalesce key: ->(user_id, *) { user_id }, on_conflict: :replace, debounce: 10.seconds
+  limits_concurrency key: ->(user_id, *) { user_id }
+  limits_rate to: 2, per: 1.second, burst: 2, group: "Crm", key: :global
+
+  def perform(user_id, attributes)
+    Crm.update_contact(user_id, attributes)
+  end
+end
+
+SyncContactJob.perform_later(user.id, user.slice(:name, :email))
+```
+
+Each control acts at a different step of the job's life:
+
+| Step | What happens | Control |
+| --- | --- | --- |
+| `perform_later` | The call replaces the user's pending job's arguments, or creates the job. While the job is scheduled, the call can move it later, to 10 seconds after the call, but never earlier. The job keeps the concurrency and rate limit keys of the call that created it | `coalesce` |
+| The job is due | It takes the user's concurrency slot, or is blocked until the running sync finishes | `limits_concurrency` |
+| A worker claims it | The quota admits it, or it waits as a scheduled job and gives its concurrency slot back. When it's due again, it takes a slot or is blocked, and the next claim checks the quota again | `limits_rate` |
+| `perform` starts | The job reads its latest arguments, and the key is free, so the next call creates the next pending job | `coalesce` |
+| `perform` finishes | The concurrency slot is free, and the user's blocked job becomes ready | `limits_concurrency` |
+
+A job that's blocked or waiting on the quota hasn't started, so calls keep replacing its arguments. The quota counts claims, not requests to the CRM, so make one request in each run. See Solid Queue Rate Limit's [recipes](https://github.com/dtcristo/solid_queue-rate_limit#recipes) for picking `burst:`, and its recipe that [batches calls under a quota](https://github.com/dtcristo/solid_queue-rate_limit#batch-calls-under-a-quota).
+
 ## `coalesce` or `limits_concurrency`?
 
 `coalesce` limits how many jobs wait. [`limits_concurrency`](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#concurrency-controls) limits how many run.
@@ -377,31 +451,34 @@ With `coalesce`, a retry can't be discarded by the key, and a blocked retry wait
 
 ## Things to know
 
-- The first call wins. It sets the job's schedule, queue, priority and concurrency key, and later calls don't change them. With `debounce:`, later calls can move the schedule. See [Collecting jobs and scheduling](#collecting-jobs-and-scheduling) and [Debouncing](#debouncing).
+- It's a separate gem that adds to Solid Queue from the outside, with its own tables. It only works with the Solid Queue adapter, because a foreign key to the job and a shared transaction are what let it work without a time window to configure.
+- The first call wins. It sets the job's schedule, queue, priority, concurrency key and rate limit key, and later calls don't change them. With `debounce:`, later calls can move the schedule. With `:replace`, they replace the arguments. See [Collecting jobs and scheduling](#collecting-jobs-and-scheduling) and [Debouncing](#debouncing).
 - With `:collect`, a full job is sealed but still waits for its time, and the next call opens a new job. See [Collecting jobs and scheduling](#collecting-jobs-and-scheduling).
 - Coalesced jobs can overlap, because the key is free as soon as a job starts. Use `limits_concurrency` to prevent that. See [Recurring jobs and concurrency limits](#recurring-jobs-and-concurrency-limits).
 - `ActiveJob.perform_all_later` can admit some calls and then raise, unless you wrap it in a queue-database transaction. See [Bulk enqueues](#bulk-enqueues).
 - `successfully_enqueued?` doesn't tell you what happened to a call, and `ActiveJob.perform_all_later` skips enqueue callbacks. Read `coalesce_status`. See [Enqueue outcomes](#enqueue-outcomes).
 - A transaction on your app's database doesn't cover an enqueue to a separate queue database. See [Transactions](#transactions).
+- It works with [Solid Queue Rate Limit](https://github.com/dtcristo/solid_queue-rate_limit), which checks its limit when a worker claims the job, after calls have coalesced at enqueue. See [Sync the latest state one at a time, under an API quota](#sync-the-latest-state-one-at-a-time-under-an-api-quota).
 
 ## Compatibility
 
 | Dependency | Supported |
 | --- | --- |
 | Ruby | 3.2 and newer |
-| Rails | 7.1, 7.2, 8.0 and 8.1. CI also runs Rails main, except on Ruby 3.2 |
-| Solid Queue | 1.7 |
+| Rails | 7.1, 7.2, 8.0 and 8.1. CI also runs Rails main |
+| Solid Queue | 1.7. CI runs 1.7.0, 1.7.1, 1.7.2 and main |
 | Database | MySQL, PostgreSQL and SQLite |
+| [Solid Queue Rate Limit](https://github.com/dtcristo/solid_queue-rate_limit) | Optional. CI tests 0.2 alongside |
 
-CI runs Ruby 3.2, 3.3, 3.4 and 4.0 against all three databases.
+CI runs each Rails and Solid Queue version against all three databases. Ruby 3.2 runs with Rails 7.1, 3.3 with 7.2, 3.4 with 8.0, and 4.0 with the rest.
 
 | Feature | Behaviour |
 | --- | --- |
-| `perform_later` | Coalesces, and stores the call with `:collect` |
-| `perform_all_later` | Coalesces in sorted key order, with one transaction per discard admission or collecting job. See [Bulk enqueues](#bulk-enqueues) |
+| `perform_later` | Coalesces, and stores the call with `:replace` or `:collect` |
+| `perform_all_later` | Coalesces in sorted key order, with one transaction per discard admission, replacing key or collecting job. See [Bulk enqueues](#bulk-enqueues) |
 | `perform_now` | Runs the call on its own. `perform_calls` receives one call |
 | `SolidQueue::Batch` | Coalesces within each batch. See [Solid Queue batches](#solid-queue-batches) |
-| Recurring tasks | `:discard` works. `:collect` and `debounce:` make the task's configuration invalid |
+| Recurring tasks | `:discard` works. `:replace`, `:collect` and `debounce:` make the task's configuration invalid |
 | Retries | Keep the job's calls, and never coalesce. See [Retries](#retries) |
 | Other adapters | Ignore `coalesce`, including `debounce:` and `max_wait:`. Each call runs on its own. See [Testing](#testing) |
 
@@ -417,20 +494,20 @@ coalesce key:, on_conflict: :discard, max_calls: nil, on_full: nil, debounce: ni
 ```
 
 - `key` is required. See [Keys](#keys).
-- `on_conflict` is `:discard` or `:collect`. Anything else raises `ArgumentError`.
+- `on_conflict` is `:discard`, `:replace` or `:collect`. Anything else raises `ArgumentError`. See [Replacing arguments](#replacing-arguments) and [Collecting calls](#collecting-calls).
 - `max_calls` is only allowed with `:collect`. It's a positive integer, 100 by default.
 - `on_full` is only allowed with `:collect`. It's `:wait`, the default, or `:dispatch`. See [Collecting jobs and scheduling](#collecting-jobs-and-scheduling).
 - `debounce` is a positive duration. Each call pushes a pending job back to that long from now. See [Debouncing](#debouncing).
 - `max_wait` is a duration greater than `debounce`, and needs `debounce`. It's optional. See [Debouncing](#debouncing).
 
-An invalid option raises `ArgumentError` when the class loads.
+Except for `key:`, an invalid option raises `ArgumentError` when the class loads. The `key:` declaration accepts any value, like `limits_concurrency`.
 
 ## Keys
 
 `key` takes the same forms as the `key` of [`limits_concurrency`](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#concurrency-controls), and is built the same way:
 
 ```ruby
-coalesce key: :global                                       # Static job-wide key
+coalesce key: :global                                       # Literal class-wide key: JobClass/global
 coalesce key: "global"                                      # Same literal component
 coalesce key: ->(account_id) { account_id }                 # Distinct per account
 coalesce key: ->(account) { account }                       # Active Record class and ID
@@ -441,16 +518,26 @@ coalesce key: ->(account_id, kind) { [ account_id, kind ] } # Composite key
 - A Proc receives the job's arguments.
 - The result is joined into a string, so `1` and `"1"` give the same key.
 - An array's items are joined with `/`, so `[ "a/b" ]` and `[ "a", "b" ]` give the same key.
-- A Proc that returns `nil` gives the class-wide key, so all of those calls merge.
+- A Proc that returns `nil` gives the bare class-wide key, `JobClass`, so all of those calls merge.
+- A declaration of `nil` or `false` disables coalescing, as it disables `limits_concurrency`, so `key: nil` isn't a class-wide key. For one key per class, use a literal such as `:global`, or a Proc that returns `nil`. Other unsupported declaration types, such as `key: 123`, give the class-wide key.
+- Blank declarations still coalesce: `key: ""` gives `JobClass/`, and `key: []` or `key: {}` gives `JobClass`. These keys are scoped to the batch too.
 - Keys longer than 255 characters fail on MySQL.
 
 Keys are always scoped to the job class name, and there's no `group` option, so two classes can't share a key. In a [Solid Queue batch](#solid-queue-batches) they're scoped to the batch too.
 
 The key column is declared like the one on Solid Queue's semaphores, with the database's default collation and a unique index. That's upstream parity, and it isn't a guarantee of bytewise uniqueness. Under a case- and accent-insensitive collation such as MySQL's `utf8mb4_0900_ai_ci`, `Job/a`, `Job/A` and `Job/á` compare equal and coalesce together. Under a case-sensitive or binary collation they stay distinct.
 
+## Replacing arguments
+
+With `on_conflict: :replace`, a call that finds a pending job writes its whole Active Job payload over the job's, and the job runs `perform` with it. Custom fields from your own `serialize` come from that call too, and ones it doesn't set are gone. Nothing older is kept, so there's no call table to fill and no `max_calls`. The job keeps its ID, `active_job_id`, queue, priority, batch, concurrency key, [Solid Queue Rate Limit](https://github.com/dtcristo/solid_queue-rate_limit) key and schedule, unless [`debounce:`](#debouncing) moves it. Calls with the same coalescing key should give the same concurrency and rate limit keys, because only the first call's are used.
+
+The key is released when a worker starts the job, and the job's payload is read again after that, before Active Job deserializes it. So a replacement admitted before the start runs in that run, even if a worker had already claimed the job, and a call after it opens the next job. "Latest" means the last call admitted under the key's lock, not a timestamp or a revision of your data.
+
+A replaced call reports `:replaced`, and its `provider_job_id` is the pending job. A retry runs the arguments of the run it retries, with its own progress and counters, and new calls never replace it.
+
 ## Collecting calls
 
-With `on_conflict: :collect`, no call is suppressed. Every accepted call is stored, including the first, and belongs to one job from the moment it's enqueued. That job runs `perform_calls` with its calls, as in the [batch recipe](#batch-calls-together):
+With `on_conflict: :collect`, no call is suppressed. Every accepted call is stored, including the first, and belongs to one job from the moment it's enqueued. That job runs `perform_calls` with its calls, as in the [collect recipe](#collect-calls-into-one-run):
 
 ```ruby
 def perform_calls(calls)
@@ -510,7 +597,7 @@ call D             job 3         running   running   open
 
 By default, sealing doesn't dispatch anything. A full job still waits for its time, and it runs like any other job. `max_calls` is the most calls one run takes, not a limit on how many can wait. The one exception comes from lowering it: a job already over the new size gets sealed as it is, and its run takes all its calls.
 
-With `on_full: :dispatch`, a job that fills doesn't wait for the rest of its delay, as in [this recipe](#run-a-batch-at-n-calls-or-t-seconds). With `.set(wait: 30.seconds)`:
+With `on_full: :dispatch`, a job that fills doesn't wait for the rest of its delay, as in [this recipe](#collect-until-n-calls-or-t-seconds). With `.set(wait: 30.seconds)`:
 
 A job that fills in 5 seconds becomes ready as the call that filled it commits, and one that doesn't fill runs at 30 seconds. The job's `scheduled_at` moves to that moment. Workers still have to be free, and if `limits_concurrency` has no room the job blocks until it does. This only matters for a delayed job, because any other job isn't waiting for its time.
 
@@ -534,7 +621,7 @@ To raise throughput on one key, use `ActiveJob.perform_all_later`. It stores up
 
 By default a job takes its time from its first call, so during a burst it can run partway through and need another run straight after. With `debounce:`, each call pushes the pending job back, so it runs once calls have stopped. With [this recipe's](#debounce-until-activity-stops) `debounce: 30.seconds, max_wait: 5.minutes`:
 
-A job comes due 30 seconds after the last call, and no later than 5 minutes after it opened. It works with `on_conflict: :discard` and `:collect`, and `coalesce_status` reports the same outcomes as before. It adds no table, column, timer or process: the job's `scheduled_at` holds the time, and the dispatcher fires it as usual.
+A job comes due 30 seconds after the last call, and no later than 5 minutes after it opened. It works with `on_conflict: :discard`, `:replace` and `:collect`, and `coalesce_status` reports the same outcomes as before. It adds no table, column, timer or process: the job's `scheduled_at` holds the time, and the dispatcher fires it as usual.
 
 A call's time comes from these rules, in this order:
 
@@ -550,7 +637,7 @@ Only a scheduled job moves. A job that's ready, blocked or claimed stays as it i
 
 `max_wait` only sets when a job comes due. It doesn't promise when the job runs: workers have to be free, and `limits_concurrency` can block the job, because Solid Queue applies [concurrency limits to scheduled jobs](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#scheduled-jobs) when they're due. It's optional, but without it a key that keeps getting calls can delay its job indefinitely.
 
-The clock starts when a job opens, and each open job has its own. A new batch after one fills gets a full `max_wait`, and so does a new job after one starts.
+The clock starts when a job opens, and each open job has its own. A new job after one fills gets a full `max_wait`, and so does a new job after one starts.
 
 With `:collect`, a job can run when it's quiet, when it's full, or at the cap, whichever comes first:
 
@@ -573,7 +660,7 @@ calls     A    B    C
 job 1     A----B----C----run
 ```
 
-A batch at N calls or T seconds, with `max_calls: 2`, `on_full: :dispatch` and `.set(wait: 30.seconds)`. B fills job 1, and C opens job 2 with its own wait:
+Collecting until N calls or T seconds, with `max_calls: 2`, `on_full: :dispatch` and `.set(wait: 30.seconds)`. B fills job 1, and C opens job 2 with its own wait:
 
 ```text
 seconds   0    10   20   30   40   50
@@ -605,9 +692,10 @@ job 1     A----B----C---------run
 - `:created` means it created a pending job. With `:collect`, that's the first call of each job.
 - `:discarded` means a pending job already held the key, and the call was suppressed.
 - `:collected` means it was stored for the pending job.
+- `:replaced` means its arguments replaced the pending job's.
 - `nil` means this instance has no recorded admission.
 
-So a call's data was stored if the status is `:created` or `:collected`, and it wasn't if it's `:discarded`:
+So a call's data was stored if the status is `:created`, `:replaced` or `:collected`, and it wasn't if it's `:discarded`. A replacement is a snapshot: a later call can replace it in turn.
 
 ```ruby
 # on_conflict: :collect
@@ -626,6 +714,8 @@ call.coalesce_status # :created, so a job runs with these arguments
 | --- | --- | --- | --- | --- |
 | Created a job | `:created` | The new job | `true` | Yes |
 | Joined with `:collect` | `:collected` | The open job | `true` | Yes |
+| Joined with `:replace` | `:replaced` | The open job | `true` | Yes, until a later call replaces it |
+| Superseded by a later `:replace` call in the same bulk enqueue | `:discarded` | The open job | `false` | No |
 | Joined with `:discard`, single | `:discarded` | The open job | `true`, set by Active Job | No |
 | Joined with `:discard`, bulk | `:discarded` | The open job | `false` | No |
 | Concurrency conflict destroyed the job, single | `nil` | `nil` | `true`, set by Active Job | No |
@@ -641,7 +731,7 @@ call.coalesce_status # :created, so a job runs with these arguments
 
 - `false` here includes `nil`, which is what `successfully_enqueued?` returns until an enqueue has been tried.
 - After a `before_enqueue` abort, `perform_later` returns `false`, as it does for any job. Pass a block to `perform_later` if you need the instance.
-- A failed enqueue raises `SolidQueue::Job::EnqueueError`, so only an instance you built yourself can be read afterwards. Nothing resets a reused instance's status or `provider_job_id`.
+- A database failure during a single enqueue raises `SolidQueue::Job::EnqueueError`. Bulk enqueues raise the original Active Record error. Only an instance you built yourself can be read afterwards. Nothing resets a reused instance's status or `provider_job_id`.
 - A deferred call that gets rolled back stays as it was before the commit, and is never stored. Rails 7.2 with `load_defaults 7.2` defers by default on Solid Queue, so there a rollback looks like this too, instead of leaving stale values.
 - On Rails 7.2 and 8.0, `retry_job` enqueues a copy of the job, so the worker's instance doesn't change at all. Read the result from what `retry_job` returns.
 
@@ -659,9 +749,9 @@ jobs = products.map { |product| ReindexProductJob.new(product.id) }
 ActiveJob.perform_all_later(jobs)
 ```
 
-This uses fewer locks and transactions than one `perform_later` per call. Native Solid Queue stores a whole [`ActiveJob.perform_all_later`](https://api.rubyonrails.org/classes/ActiveJob.html#method-c-perform_all_later) in one transaction, so it's all-or-nothing. With coalesced jobs in the list it isn't, unless you ask for it. Outside your own transaction, it stores ordinary jobs first, in one native transaction. Coalesced calls follow, sorted by key, with one transaction per discard admission or collecting job. A key's lock lasts until its transaction commits, and one transaction for the whole call would hold every key's lock until the last job was in. This way it holds one key's lock for one job's calls.
+This uses fewer locks and transactions than one `perform_later` per call. Native Solid Queue stores a whole [`ActiveJob.perform_all_later`](https://api.rubyonrails.org/classes/ActiveJob.html#method-c-perform_all_later) in one transaction, so it's all-or-nothing. With coalesced jobs in the list it isn't, unless you ask for it. Outside your own transaction, it stores ordinary jobs first, in one native transaction. Coalesced calls follow, sorted by key, with one transaction per discard admission, replacing key or collecting job. A key's lock lasts until its transaction commits, and one transaction for the whole call would hold every key's lock until the last job was in. This way it holds one key's lock for one job's calls.
 
-Before it writes anything, the call works out the keys of all coalesced calls, the payloads of all `:collect` calls, and the payload of each key's first `:discard` call. If a key Proc raises or an argument can't be serialized, the call raises with nothing written. A repeated `:discard` call is never stored, so an argument on it that can't be serialized stays silently discarded, as with a single `perform_later`.
+Before it writes anything, the call works out the keys of all coalesced calls, the payloads of all `:collect` calls, the payload of each key's first `:discard` call, and the payload of each key's last `:replace` call. With `:replace`, only that last call is admitted. If it creates the job, the job's queue, priority and other fields come from it. The calls before it report `:discarded` and don't have to serialize, though they can still move a debounced job. If a key Proc raises or an argument can't be serialized, the call raises with nothing written. A repeated `:discard` call is never stored, so an argument on it that can't be serialized stays silently discarded, as with a single `perform_later`.
 
 After that, only a database error or a `coalesce.solid_queue` subscriber that raises can fail the call. There's one exception. A job's concurrency key comes from its first call, and which call that is depends on the database, so a concurrency key Proc can raise on a later job's first call. In every case, earlier work stays committed and has its outcomes, and later calls have no outcome.
 
@@ -675,7 +765,7 @@ This stores each call once. Calls destroyed by a `limits_concurrency` conflict w
 
 Trust outcomes only from a call that didn't raise, or for this recovery. A failed enqueue of an instance you've enqueued before can show its old outcome.
 
-A database failure on coalesced calls raises `SolidQueue::Job::EnqueueError`. One on ordinary jobs raises the raw Active Record error, as native bulk does. A single call can raise either.
+A database failure raises the original Active Record error for both ordinary and coalesced jobs, as native bulk does. A single `perform_later` wraps database failures in `SolidQueue::Job::EnqueueError`. Errors from `coalesce.solid_queue` subscribers propagate unchanged for both APIs, including Active Record errors. A subscriber failure doesn't undo work that has already committed or clear its outcomes.
 
 Only the order of each key's calls is guaranteed. Native bulk creates jobs in input order. Here, ordinary jobs come first, then coalesced calls sorted by key.
 
@@ -715,7 +805,7 @@ If Solid Queue shares your app's database, a `perform_later` inside your transac
 
 A retry is the same work continuing, not a new candidate for coalescing. It can't be suppressed by a pending job, and later calls can't join it. A job keeps its calls through `retry_on`, `rescue_from` with `retry_job`, an `ActiveJob::Continuable` resume, a manual retry of a failed job, and a re-run after its worker was released. If a retry can't be enqueued, the job fails and keeps its calls.
 
-[Active Job handles retries](https://guides.rubyonrails.org/active_job_basics.html#retrying-or-discarding-failed-jobs), and Solid Queue keeps [failed jobs](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#failed-jobs-and-retries) until you retry or discard them. Delivery is at-least-once. There's no per-call acknowledgement, so a retry runs all of the job's calls again and `perform_calls` has to be idempotent. A `step` cursor can skip finished work, as in [Resume a long batch](#resume-a-long-batch), but `perform_calls` still receives every call.
+[Active Job handles retries](https://guides.rubyonrails.org/active_job_basics.html#retrying-or-discarding-failed-jobs), and Solid Queue keeps [failed jobs](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#failed-jobs-and-retries) until you retry or discard them. Delivery is at-least-once. There's no per-call acknowledgement, so a retry runs all of the job's calls again and `perform_calls` has to be idempotent. A `step` cursor can skip finished work, as in [Resume a long collecting job](#resume-a-long-collecting-job), but `perform_calls` still receives every call.
 
 ## Deleted records
 
@@ -725,7 +815,7 @@ Every call row stays until its job is destroyed, including calls skipped because
 
 ## Recurring jobs and concurrency limits
 
-A [recurring task](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#recurring-tasks) can use `:discard`. A tick that finds a pending job is suppressed and not recorded in `solid_queue_recurring_executions`. A recurring task can't use `:collect` or `debounce:`: its configuration is invalid. A tick passes no time, so it would get the window, and an interval shorter than the window could stop the job from ever running.
+A [recurring task](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#recurring-tasks) can use `:discard`. A tick that finds a pending job is suppressed and not recorded in `solid_queue_recurring_executions`. A recurring task can't use `:replace`, `:collect` or `debounce:`: its configuration is invalid. A tick that joined with either of the first two would record the pending job again, and the unique index would roll back what it added. A tick passes no time, so it would get the window, and an interval shorter than the window could stop the job from ever running.
 
 To keep one follow-up, coalesce pending work and block on the limit, as in the [leading edge](#run-on-the-leading-edge) and [recurring](#coalesce-a-recurring-task) recipes. To drop busy ticks with no follow-up, use `limits_concurrency on_conflict: :discard` alone, after reading [`coalesce` or `limits_concurrency`?](#coalesce-or-limits_concurrency).
 
@@ -741,17 +831,45 @@ A runs right away. B arrives during that run and opens job 2, which blocks on th
 
 `:global` is a literal in both APIs, and coalescing and concurrency keep separate database records. A semaphore's [`duration`](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#concurrency-controls) can expire, so a concurrency limit isn't an absolute guarantee against overlap.
 
-The concurrency key of a coalesced job is the one computed for the call that created it, and a blocked job still holds its coalesce key, since it hasn't started. `:collect` works with `on_conflict: :block`. It can't be combined with `limits_concurrency` with `on_conflict: :discard`, in either order, because a conflict would destroy a job holding calls, so that raises `ArgumentError` when the class loads. `:discard` can, and the destroyed job frees the key.
+The concurrency key of a coalesced job is the one computed for the call that created it, and a blocked job still holds its coalesce key, since it hasn't started. `:replace` and `:collect` work with `on_conflict: :block`. They can't be combined with `limits_concurrency` with `on_conflict: :discard`, in either order, because a conflict would destroy a job holding replaced arguments or calls, so that raises `ArgumentError` when the class loads. `:discard` can, and the destroyed job frees the key.
 
 ## Solid Queue batches
 
-A coalesced job can be part of a [`SolidQueue::Batch`](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#batch-jobs), as in [this recipe](#dedupe-jobs-in-a-solid-queue-batch). Batches need Solid Queue's own optional migration, and nothing more from this gem.
+A coalesced job can be part of a [`SolidQueue::Batch`](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#batch-jobs). Batches need Solid Queue's own optional migration, and nothing more from this gem.
+
+Use this when a callback should run once a group of jobs is done, and jobs in that group can ask for the same work.
+
+```ruby
+class ReindexProductJob < ApplicationJob
+  coalesce key: ->(product_id) { product_id }
+
+  def perform(product_id)
+    Product.find(product_id).reindex!
+  end
+end
+
+class ImportSupplierJob < ApplicationJob
+  def perform(supplier_id)
+    Supplier.find(supplier_id).import_products.each do |product_id|
+      batch.enqueue { ReindexProductJob.perform_later(product_id) }
+    end
+  end
+end
+
+SolidQueue::Batch.enqueue(on_success: PublishCatalogJob) do
+  supplier_ids.each { |supplier_id| ImportSupplierJob.perform_later(supplier_id) }
+end
+```
+
+Each importer adds to the batch while it runs, and that running job keeps the batch open. Two importers that reach the same pending product share one reindex. If that reindex has already started, the later call opens a new job, so the later change still gets reindexed. `PublishCatalogJob` runs once, after the importers and every reindex are done.
+
+A few rules apply:
 
 - Calls with the same key share one job, and that job belongs to that batch alone. The same key in another batch, or outside a batch, runs separately. `limits_concurrency` isn't scoped to a batch, so it still stops those jobs overlapping.
-- `total_jobs` counts jobs, not calls. A call that joins a job adds nothing, and the job after a `:collect` job seals counts as another.
-- A batched key starts with its batch, as in `SolidQueue::Batch/7/ReindexProductJob/42`. `coalesce.solid_queue` reports it that way, and the prefix counts towards MySQL's 255 characters.
+- `total_jobs` counts jobs, not calls. A call that joins or replaces a job adds nothing, and the job after a `:collect` job seals counts as another.
+- A batched key starts with its batch, as in `Batch/7/ReindexProductJob/42`. `coalesce.solid_queue` reports it that way, and the prefix counts towards MySQL's 255 characters.
 - A running job adds to its batch with `batch.enqueue`. Without that a call isn't in the batch, because Solid Queue doesn't set a current batch while a job runs. Adding from anywhere else races the batch finishing, and raises `SolidQueue::Batch::AlreadyFinished` if it lost.
-- `batch.enqueue` is a transaction, so a block that raises rolls back everything in it. A deadlock isn't retried inside it. It raises `SolidQueue::Job::EnqueueError` and rolls back the block, as in [your own transaction](#rules-and-limitations). A block that opens several keys holds the batch's row while it waits for the next key, so concurrent blocks on one batch can deadlock. If jobs add to a batch at the same time, use one `batch.enqueue` per call, as in the recipe.
+- `batch.enqueue` is a transaction, so a block that raises rolls back everything in it. A deadlock isn't retried inside it. A single enqueue raises `SolidQueue::Job::EnqueueError`, and a bulk enqueue raises `ActiveRecord::Deadlocked`; both roll back the block, as in [your own transaction](#rules-and-limitations). A block that opens several keys holds the batch's row while it waits for the next key, so concurrent blocks on one batch can deadlock. If jobs add to a batch at the same time, use one `batch.enqueue` per call, as in the example.
 - With `enqueue_after_transaction_commit`, which `load_defaults 8.2` turns on, calls wait until the block commits. A failure then can't roll the block back, and a deferred `perform_all_later` only keeps the batch for jobs built inside the block. Solid Queue's ordinary jobs do the same.
 - Bulk discards delete jobs without callbacks, so a batch left with no jobs finishes when Solid Queue's batch maintenance next runs.
 - A callback job isn't part of its batch, so a coalesced one uses the key it would use outside a batch.
@@ -764,7 +882,7 @@ A job that fails before starting, for example because its worker died or because
 
 ## Changing a job's configuration
 
-A job that gets a key records how it was created in its own payload, as `"coalesce_on_conflict": "collect"` or `"discard"`, so a worker knows even if the class has changed since. If you remove `:collect` or `coalesce` while calls are waiting, each of those jobs raises `ActiveJob::Coalescing::CollectedJobMismatch` when it runs. Nothing has run at that point, `retry_on` and `discard_on` don't see the error, and the job fails with all of its calls. Restore the declaration and retry the failed job to run them, or discard the job to delete them.
+A job that gets a key records how it was created in its own payload, as `"solid_queue_coalesce_on_conflict": "discard"`, `"replace"` or `"collect"`, so a worker knows even if the class has changed since. If you remove `:collect` or `coalesce` while calls are waiting, each of those jobs raises `ActiveJob::Coalescing::CollectedJobMismatch` when it runs. Nothing has run at that point, `retry_on` and `discard_on` don't see the error, and the job fails with all of its calls. Restore the declaration and retry the failed job to run them, or discard the job to delete them.
 
 That's a way to recover, not a way to deploy. To remove `:collect` or `coalesce` without failures, stop enqueuing, wait for `SolidQueue::CoalescedCall.waiting` to be empty, and only then deploy the change. Workers on the old and new code can overlap in a rolling deploy, so a job can fail on one of them and need the same recovery.
 
@@ -773,6 +891,10 @@ That's a way to recover, not a way to deploy. To remove `:collect` or `coalesce`
 | Remove `:collect` or `coalesce` | The job fails with its calls, as above |
 | Switch `:collect` to `:discard` | The job fails with its calls, as above. The next call doesn't count on that job, and creates a new one |
 | Switch `:discard` to `:collect` | The next call doesn't join the discarding job, and creates a new one. The old job runs one call from its own arguments |
+| Switch `:discard` to `:replace` | The next call doesn't replace the discarding job's arguments, and creates a new one. The old job runs with its own arguments |
+| Switch `:collect` to `:replace` | The job fails with its calls, as above. The next call doesn't count on that job, and creates a new one |
+| Switch `:replace` to `:collect` | The next call doesn't join the replacing job, and creates a new one. The old job runs its latest arguments as one call |
+| Switch `:replace` to `:discard`, or remove `coalesce` | Calls are discarded into the replacing job, or run on their own. It runs its latest arguments, and nothing needs draining |
 | Change `limits_concurrency` to `on_conflict: :discard` after removing `:collect` | A conflict blocks the job instead of destroying it, so it reaches a worker and fails with its calls |
 | Change the queue adapter | Waiting jobs still run their calls. A retry of one raises `CollectedJobMismatch`, and the job fails with its calls |
 | Remove `perform_calls` | The run raises `NotImplementedError`, and the job fails with its calls, unless a handler such as `discard_on Exception` takes it |
@@ -784,7 +906,7 @@ That's a way to recover, not a way to deploy. To remove `:collect` or `coalesce`
 
 Solid Queue only deletes calls along with their job. Deleting call rows yourself isn't supported, and neither is changing `calls_count`. If you do, a collecting job with no calls left raises `CollectedJobMismatch` instead of running its own arguments, which are a copy of its first call. A job that lost only some of its calls runs the rest, and nothing reports the loss.
 
-Jobs enqueued by version 0.1 don't have this record, so drain them before you upgrade. See [UPGRADING.md](UPGRADING.md).
+Jobs enqueued before 0.3.0 don't have the prefixed marker, and the old name isn't read. Drain coalesced jobs before upgrading, including retrying or discarding failed ones on the old version. See [UPGRADING.md](UPGRADING.md).
 
 ## Rules and limitations
 
@@ -820,7 +942,7 @@ Two notifications exist:
 
 | Event | When | Payload |
 | --- | --- | --- |
-| `coalesce.solid_queue` | A call was admitted, including the one that created the job | `status` (`:created`, `:discarded`, `:collected`), `key`, `job_id`, `active_job_id`, `class_name` |
+| `coalesce.solid_queue` | A call was admitted, including the one that created the job | `status` (`:created`, `:discarded`, `:replaced`, `:collected`), `key`, `job_id`, `active_job_id`, `class_name` |
 | `drop_coalesced_call.solid_queue` | A collected call was skipped on this attempt because its record is gone | `call_id`, `job_id`, `active_job_id`, `class_name`, `exception_class` |
 
 `SolidQueue::LogSubscriber` logs the first at debug level and the second at warn level. Neither logs arguments or payloads, and neither logs the key, which your app defines. The key is only in the event's payload.

data/UPGRADING.md

@@ -1,4 +1,31 @@
-# Upgrading to version 0.2.x
+# Upgrading from version 0.2.0 to 0.3.0
+
+The serialized job marker is now `solid_queue_coalesce_on_conflict`, and the old `coalesce_on_conflict` name is no longer read. Drain all coalesced work on the old version before deploying. No database migration or payload conversion is provided.
+
+Batched coalescing keys also start with `Batch/<id>/` instead of `SolidQueue::Batch/<id>/`. New calls won't join pending jobs under the old keys and can create separate jobs for the same work, so affected batches must finish too.
+
+1. Pause every producer of coalesced work, including application requests, recurring tasks and batch producers. Keep the old workers and dispatcher running to drain the queue.
+2. Wait for all coalesced jobs to finish, including scheduled, ready, blocked, running and retrying jobs. Retry or discard failed jobs on the old version. Check every class that used `coalesce`, including ones whose declarations have since changed, with the query below.
+3. Wait for affected batches to finish. To conservatively check all batches, wait until `SolidQueue::Batch.where(finished_at: nil).count` is zero.
+4. Stop the old application and Solid Queue processes, deploy the new version to all producers, workers, dispatchers and schedulers together, then resume producers. Don't run both versions against coalesced work or affected batches.
+
+For example, replace these names with all your coalesced job classes and wait until the result is zero. Failed jobs are included, so retry or discard them before continuing:
+
+```ruby
+SolidQueue::Job.where(finished_at: nil, class_name: %w[ ReindexDocumentsJob SendDigestJob ]).count
+```
+
+Retrying an old failed job after deployment doesn't rewrite its payload and isn't a supported upgrade path. Preserved finished jobs need no drain, but replaying their old payloads after upgrading isn't supported either.
+
+Update code that depends on these errors or key declarations:
+
+- `ActiveJob.perform_all_later` now raises the original Active Record database error for coalesced calls, including `ActiveRecord::ValueTooLong` and `ActiveRecord::Deadlocked`. Update bulk error handlers that rescue `SolidQueue::Job::EnqueueError`. Single enqueues still wrap database errors in `SolidQueue::Job::EnqueueError`, and subscriber errors remain raw.
+- `coalesce(key:)` no longer rejects unsupported or blank declarations. Unsupported truthy types, such as `key: 123`, give a class-wide key. Blank strings and empty arrays or hashes still coalesce. Only `nil` and `false` disable coalescing. Check declarations that previously relied on `ArgumentError`; all other option validations remain.
+
+Update notification subscribers, log parsers or other consumers that match the old batch key prefix. `coalesce.solid_queue` now reports keys such as `Batch/7/ReindexProductJob/42`.
+
+# Upgrading from version 0.1.0 to 0.2.0
+
 This version replaces the gem's tables and the options of `coalesce`. There's no in-place migration for waiting calls, so drain them first. The generator skips an app that already has its migration, so this upgrade needs a migration of your own.
 
 Stop enqueuing jobs that use `coalesce`, and on 0.1.0 wait until none of those jobs are left. This query includes scheduled, blocked, running and failed jobs, so retry or discard the failed ones:

data/app/models/solid_queue/coalesced_call.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module SolidQueue
-  # The Active Job payload of one collected perform_later call. It belongs to one
-  # job from the moment it's admitted, across that job's retries, until the job is
-  # destroyed.
+  # The Active Job payload of one collected perform_later call. It's kept from the
+  # moment it's admitted until the job that holds it is destroyed, and a retry moves
+  # it to the new job.
   class CoalescedCall < Record
     belongs_to :job
 

data/app/models/solid_queue/job/coalescible.rb

@@ -13,13 +13,28 @@ module SolidQueue
         before_destroy :release_coalesce_key, prepend: true
       end
 
+      # What a replacement keeps from the job: what identifies it, its place in line,
+      # its batch, its marker, the semaphore Solid Queue recorded for it and the key
+      # solid_queue-rate_limit charges it to, so the first call's keys win. Solid Queue 1.7.2
+      # names the semaphore entry ConcurrencyControls::CONCURRENCY_LOCK_KEY, which 1.7.0 and 1.7.1 lack.
+      REPLACEMENT_KEPT_KEYS = %w[ job_class job_id queue_name priority enqueued_at scheduled_at batch_id callback_batch_id solid_queue_coalesce_on_conflict solid_queue_concurrency_lock solid_queue_rate_limit_key ]
+
       class_methods do
         # Every call in active_jobs has the same key. Returns the job if a call
-        # created one, nil if the calls joined the open job.
-        def enqueue_coalesced(key, active_jobs, payloads = nil)
-          return collect_coalesced(key, active_jobs, payloads || active_jobs.map(&:serialize)) if active_jobs.first.class.coalesce_collect?
+        # created one, nil if the calls joined the open job. A replacing call's
+        # payloads are only its last call's.
+        def enqueue_coalesced(key, active_jobs, payloads = nil, wrap_errors: false)
+          if active_jobs.first.class.coalesce_collect?
+            payloads ||= raising_enqueue_errors(wrap_errors) { active_jobs.map(&:serialize) }
+            return collect_coalesced(key, active_jobs, payloads, wrap_errors: wrap_errors)
+          end
+
+          if active_jobs.first.class.coalesce_replace?
+            payloads ||= raising_enqueue_errors(wrap_errors) { [ active_jobs.last.serialize ] }
+            return replace_coalesced(key, active_jobs, payloads.last, wrap_errors: wrap_errors)
+          end
 
-          enqueued_job, open_job_id = raising_enqueue_errors do
+          enqueued_job, open_job_id = raising_enqueue_errors(wrap_errors) do
             retrying_deadlocks { admit_discarding(key, active_jobs) }
           end
 
@@ -31,11 +46,14 @@ module SolidQueue
         # So a key or a payload that can't be built raises before anything is written.
         # A repeated :discard call is never stored, so its arguments don't have to
         # serialize, as with perform_later. The first one's only get checked here,
-        # because its job is built later, if there's no open job to find.
+        # because its job is built later, if there's no open job to find. Only the
+        # last :replace call is stored, so the ones it supersedes don't serialize either.
         def prepare_all_coalesced(active_jobs)
           active_jobs.group_by(&:coalesce_key).sort_by(&:first).map do |key, calls|
             if calls.first.class.coalesce_collect?
               [ key, calls, calls.map(&:serialize) ]
+            elsif calls.first.class.coalesce_replace?
+              [ key, calls, [ calls.last.serialize ] ]
             else
               calls.first.serialize
               [ key, calls ]
@@ -96,9 +114,11 @@ module SolidQueue
             enqueued_job
           end
 
-          def raising_enqueue_errors
+          def raising_enqueue_errors(wrap_errors = true)
             yield
           rescue ActiveRecord::ActiveRecordError => e
+            raise unless wrap_errors
+
             enqueue_error = EnqueueError.new("#{e.class.name}: #{e.message}").tap do |error|
               error.set_backtrace e.backtrace
             end
@@ -124,17 +144,19 @@ module SolidQueue
             coalesce_key = CoalesceKey.admit(key)
 
             unless coalesce_key.collecting?
-              enqueued_job = create_for_coalesce_key(coalesce_key, active_jobs.first) if coalesce_key.job_id.nil?
+              if coalesce_key.job_id.nil?
+                attributes = attributes_from_active_job(active_jobs.first)
+                enqueued_job = create_for_coalesce_key(coalesce_key, **attributes, arguments: attributes[:arguments].merge("solid_queue_coalesce_on_conflict" => "discard"))
+              end
+
               debounce_coalesced(coalesce_key, coalesce_key.job_id, enqueued_job ? active_jobs.drop(1) : active_jobs)
 
               [ enqueued_job, coalesce_key.job_id ]
             end
           end
 
-          def create_for_coalesce_key(coalesce_key, active_job)
-            attributes = attributes_from_active_job(active_job)
-
-            create!(**attributes, arguments: attributes[:arguments].merge("coalesce_on_conflict" => "discard")).tap do |job|
+          def create_for_coalesce_key(coalesce_key, **attributes)
+            create!(**attributes).tap do |job|
               # limits_concurrency with on_conflict: :discard destroys the job right away
               if job.persisted?
                 coalesce_key.update_columns(job_id: job.id)
@@ -149,13 +171,13 @@ module SolidQueue
           # can't leave one behind. Serialized once and before any job exists, so the
           # first call's payload is like every other call's, and a retry doesn't take
           # a new snapshot.
-          def collect_coalesced(key, active_jobs, payloads)
+          def collect_coalesced(key, active_jobs, payloads, wrap_errors:)
             max_calls = active_jobs.first.class.coalesce_max_calls
             pending = active_jobs.zip(payloads)
             enqueued_job = nil
 
             until pending.empty?
-              admitted, created_job, job_id = raising_enqueue_errors do
+              admitted, created_job, job_id = raising_enqueue_errors(wrap_errors) do
                 retrying_deadlocks { transaction { admit_collected(key, pending, max_calls) } }
               end
 
@@ -177,7 +199,7 @@ module SolidQueue
               coalesce_key.destroy!
               [ 0 ]
             else
-              created_job = create_collecting(*calls.first) if coalesce_key.job_id.nil?
+              created_job = create!(**attributes_from_payload(*calls.first, "collect")) if coalesce_key.job_id.nil?
               job_id = coalesce_key.job_id || created_job.id
 
               CoalescedCall.insert_all(calls.map { |_, payload| { job_id: job_id, arguments: payload } })
@@ -241,31 +263,75 @@ module SolidQueue
 
           # Not attributes_from_active_job, which serializes the call again, and that
           # could raise after earlier jobs committed.
-          def create_collecting(active_job, payload)
+          def attributes_from_payload(active_job, payload, on_conflict)
             attributes = {
               queue_name: active_job.queue_name || singleton_class::DEFAULT_QUEUE_NAME,
               active_job_id: active_job.job_id,
               priority: active_job.priority || singleton_class::DEFAULT_PRIORITY,
               scheduled_at: active_job.scheduled_at,
               class_name: active_job.class.name,
-              arguments: payload.merge("coalesce_on_conflict" => "collect"),
+              arguments: payload.merge("solid_queue_coalesce_on_conflict" => on_conflict),
               concurrency_key: active_job.concurrency_key
             }
             attributes[:batch_id] = active_job.batch_id if Batch.migrated?
+            attributes
+          end
+
+          # Like a collecting job, serialized once and before anything is written. The
+          # last call is the one admitted: it creates the job, or its payload replaces
+          # the job's. The calls before it are superseded, and only move the job later.
+          def replace_coalesced(key, active_jobs, payload, wrap_errors:)
+            enqueued_job, job_id = raising_enqueue_errors(wrap_errors) do
+              retrying_deadlocks { transaction { admit_replacing(key, active_jobs, payload) } }
+            end
+
+            record_coalesced(key, active_jobs, enqueued_job.present?, job_id)
 
-            create!(**attributes)
+            enqueued_job
+          end
+
+          # A job from when the class discarded or collected runs the way it was
+          # created, and can't take a payload, so the call seals it and tries again.
+          # It holds the key exclusively, so it can do that without letting go of it.
+          def admit_replacing(key, active_jobs, payload)
+            loop do
+              coalesce_key = CoalesceKey.admit_exclusively(key)
+              job = lock.find_by(id: coalesce_key.job_id) if coalesce_key.discarding?
+
+              if coalesce_key.job_id.nil?
+                enqueued_job = create_for_coalesce_key(coalesce_key, **attributes_from_payload(active_jobs.last, payload, "replace"))
+                debounce_coalesced(coalesce_key, coalesce_key.job_id, active_jobs[0...-1])
+
+                return [ enqueued_job, coalesce_key.job_id ]
+              elsif job&.created_replacing?
+                job.replace_arguments(payload)
+                debounce_coalesced(coalesce_key, job.id, active_jobs)
+
+                return [ nil, job.id ]
+              else
+                coalesce_key.destroy!
+              end
+            end
           end
 
           # A call has an outcome only if it was admitted: when on_conflict: :discard
-          # destroys the job that was just created, nothing holds the key.
+          # destroys the job that was just created, nothing holds the key. The first
+          # call is the one that creates a job, except with :replace, where it's the last.
           def record_coalesced(key, active_jobs, created, job_id)
-            active_jobs.each_with_index do |active_job, index|
-              collect = active_job.class.coalesce_collect?
-              created_by_this_call = created && index.zero?
+            active_jobs.each do |active_job|
+              job_class = active_job.class
+              admitted = job_class.coalesce_replace? ? active_jobs.last : active_jobs.first
+
+              status = if job_id.nil? then nil
+              elsif created && active_job.equal?(admitted) then :created
+              elsif job_class.coalesce_collect? then :collected
+              elsif active_job.equal?(admitted) && job_class.coalesce_replace? then :replaced
+              else :discarded
+              end
 
               active_job.provider_job_id = job_id
-              active_job.successfully_enqueued = created_by_this_call || collect
-              active_job.send(:coalesce_status=, job_id && (created_by_this_call ? :created : (collect ? :collected : :discarded)))
+              active_job.successfully_enqueued = status.in?(%i[ created replaced collected ])
+              active_job.send(:coalesce_status=, status)
             end
 
             # After every outcome, because a subscriber can raise. These calls are stored,
@@ -278,6 +344,24 @@ module SolidQueue
           end
       end
 
+      def created_replacing?
+        arguments.is_a?(Hash) && arguments["solid_queue_coalesce_on_conflict"] == "replace"
+      end
+
+      # The caller holds the job's lock, and Solid Queue takes it too before it records
+      # the job's semaphore, so neither write can undo the other.
+      def replace_arguments(payload)
+        update_column :arguments, payload.except(*REPLACEMENT_KEPT_KEYS).merge(arguments.slice(*REPLACEMENT_KEPT_KEYS))
+      end
+
+      # A replacing job's start step, before its payload is read. Releasing the key
+      # commits on its own, so the payload read after it has every replacement
+      # admitted before the release, and a call after it opens a new job.
+      def start_replacing_run
+        self.class.retrying_deadlocks { transaction { release_coalesce_key } }
+        reload
+      end
+
       # The start step. Returns what the Active Job needs to know about this run,
       # which stays in memory instead of going into its serialized data.
       #
@@ -296,14 +380,14 @@ module SolidQueue
       private
         # Whether this job's class coalesces
         def coalesced?
-          job_class.try(:coalesce_key).present?
+          !!job_class.try(:coalesce_key)
         end
 
         # Admission marks a job before giving it a key, and the class covers jobs from
         # before the marker. Anything that can't answer gets the read, so that failing
         # or discarding a job still works when its payload or its class can't be loaded.
         def may_hold_coalesce_key?
-          !arguments.is_a?(Hash) || arguments.key?("coalesce_on_conflict") || coalesced?
+          !arguments.is_a?(Hash) || arguments.key?("solid_queue_coalesce_on_conflict") || coalesced?
         rescue StandardError, ScriptError
           true
         end

data/lib/active_job/coalescing.rb

@@ -5,7 +5,7 @@ module ActiveJob
   module Coalescing
     extend ActiveSupport::Concern
 
-    COALESCE_ON_CONFLICT_BEHAVIOUR = %i[ discard collect ]
+    COALESCE_ON_CONFLICT_BEHAVIOUR = %i[ discard replace collect ]
     COALESCE_ON_FULL_BEHAVIOUR = %i[ wait dispatch ]
     DEFAULT_COALESCE_MAX_CALLS = 100
 
@@ -53,9 +53,9 @@ module ActiveJob
       class_attribute :coalesce_max_wait, instance_accessor: false
     end
 
-    # What happened to this call: +:created+, +:discarded+, +:collected+, or +nil+ if
-    # this instance has no recorded admission. It isn't serialized, so it's +nil+ on
-    # a worker's instance.
+    # What happened to this call: +:created+, +:discarded+, +:replaced+, +:collected+,
+    # or +nil+ if this instance has no recorded admission. It isn't serialized, so it's
+    # +nil+ on a worker's instance.
     #
     #   job = ReindexProductJob.perform_later(product.id)
     #   job.coalesce_status # => :discarded
@@ -83,23 +83,22 @@ module ActiveJob
       #
       # * +:key+ - Required. A String or Symbol literal, or a Proc that receives the job's
       #   arguments. It's scoped to the job class, and built like the key of +limits_concurrency+.
+      #   +nil+ and +false+ disable coalescing; other types give a class-wide key. Blank
+      #   declarations still coalesce. All keys are scoped to the batch when present.
       # * +:on_conflict+ - +:discard+, the default, suppresses a call that finds a pending
-      #   job. +:collect+ stores every call for #perform_calls.
+      #   job. +:replace+ gives the pending job the call's arguments, so it runs +perform+
+      #   with the latest ones. +:collect+ stores every call for #perform_calls.
       # * +:max_calls+ - The most calls one run takes with +:collect+. Defaults to 100.
       # * +:on_full+ - With +:collect+, +:wait+, the default, leaves a full job to wait for
       #   its time. +:dispatch+ makes it ready as it fills.
       # * +:debounce+ - A duration. Each call pushes a pending job back to that long from now.
       # * +:max_wait+ - A duration greater than +:debounce+ that caps how far a job can move.
       #
-      # An invalid option raises +ArgumentError+. The README has recipes for each of these:
+      # Except for +:key+, an invalid option raises +ArgumentError+. The README has recipes:
       # https://github.com/dtcristo/solid_queue-coalesce#recipes
       def coalesce(key:, on_conflict: :discard, max_calls: nil, on_full: nil, debounce: nil, max_wait: nil)
-        unless (key.is_a?(String) || key.is_a?(Symbol) || key.is_a?(Proc)) && key.present?
-          raise ArgumentError, "`key` must be a non-blank String or Symbol, or a Proc"
-        end
-
         unless on_conflict.in?(COALESCE_ON_CONFLICT_BEHAVIOUR)
-          raise ArgumentError, "`on_conflict` must be :discard or :collect"
+          raise ArgumentError, "`on_conflict` must be :discard, :replace or :collect"
         end
 
         if on_conflict == :collect
@@ -146,15 +145,20 @@ module ActiveJob
         coalesce_on_conflict == :collect
       end
 
+      def coalesce_replace? # :nodoc:
+        coalesce_on_conflict == :replace
+      end
+
       def limits_concurrency(**) # :nodoc:
         super.tap { ensure_coalesce_compatible_with_concurrency_controls(coalesce_on_conflict, concurrency_on_conflict) }
       end
 
       private
-        # A conflict destroys the job, and with it the calls it has collected
+        # A conflict destroys the job, and with it the arguments that replaced its own
+        # or the calls it has collected
         def ensure_coalesce_compatible_with_concurrency_controls(coalesce_on_conflict, concurrency_on_conflict)
-          if coalesce_on_conflict == :collect && concurrency_on_conflict == :discard
-            raise ArgumentError, "`coalesce` with `on_conflict: :collect` can't be combined with `limits_concurrency` with `on_conflict: :discard`"
+          if coalesce_on_conflict.in?(%i[ replace collect ]) && concurrency_on_conflict == :discard
+            raise ArgumentError, "`coalesce` with `on_conflict: :#{coalesce_on_conflict}` can't be combined with `limits_concurrency` with `on_conflict: :discard`"
           end
         end
     end
@@ -171,12 +175,12 @@ module ActiveJob
     # outlives the class's declaration. Only the job's row starts with this, when it
     # gets its key, so an instance only has it if it was read from one.
     def serialize # :nodoc:
-      @coalesce_on_conflict ? super.merge("coalesce_on_conflict" => @coalesce_on_conflict) : super
+      @coalesce_on_conflict ? super.merge("solid_queue_coalesce_on_conflict" => @coalesce_on_conflict) : super
     end
 
     def deserialize(job_data) # :nodoc:
       super
-      @coalesce_on_conflict = job_data["coalesce_on_conflict"]
+      @coalesce_on_conflict = job_data["solid_queue_coalesce_on_conflict"]
     end
 
     # Scoped to the job class name, and built like concurrency_key. In a batch it's
@@ -208,7 +212,7 @@ module ActiveJob
 
     # A retry is the same work continuing, so it can't join or suppress anything
     def coalesced_enqueue? # :nodoc:
-      self.class.coalesce_key.present? && executions.to_i.zero?
+      self.class.coalesce_key && executions.to_i.zero?
     end
 
     # A call's own time if it has one, and otherwise now plus the window. A longer
@@ -239,13 +243,16 @@ module ActiveJob
 
     private
       def coalesce_batch_scope
-        [ SolidQueue::Batch.name, batch_id ] if batch_id
+        [ "Batch", batch_id ] if batch_id
       end
 
       # Only the run of a job a worker has claimed. perform_now on an instance that
       # went through perform_later also has a provider_job_id. A collecting job always
       # looks for its run, because the marker outlives the class's key and adapter.
+      # A replacing job's run started before its payload was read.
       def start_coalesced_run
+        return if @coalesce_on_conflict == "replace"
+
         ensure_still_collecting if created_collecting?
 
         if created_collecting? || (self.class.coalesce_key && provider_job_id && self.class.queue_adapter_name == "solid_queue")

data/lib/solid_queue/coalesce/patches.rb

@@ -32,7 +32,8 @@ module SolidQueue
           if active_job.coalesced_enqueue?
             active_job.scheduled_at = active_job.coalesced_scheduled_at(options[:scheduled_at])
             ensure_coalescible
-            enqueue_coalesced(active_job.coalesce_key, [ active_job ])
+            key = raising_enqueue_errors { active_job.coalesce_key }
+            enqueue_coalesced(key, [ active_job ], wrap_errors: true)
           elsif active_job.class.coalesce_key
             continuing_coalesced_run(active_job) { super }
           else
@@ -65,11 +66,36 @@ module SolidQueue
 
       # A class can start discarding conflicts after it stopped collecting, and a
       # conflict destroys the job. A collecting job blocks instead, whatever its class
-      # says now, so it reaches a worker and fails with its calls.
+      # says now, so it reaches a worker and fails with its calls. A replacing job
+      # blocks too, because a conflict would destroy the arguments that replaced its own.
       module ConcurrencyConflicts
         private
           def handle_concurrency_conflict
-            arguments["coalesce_on_conflict"] == "collect" ? block : super
+            arguments["solid_queue_coalesce_on_conflict"].in?(%w[ replace collect ]) ? block : super
+          end
+      end
+
+      # Solid Queue writes the whole payload when it records a semaphore, from a copy
+      # read before it locked anything. For a replacing job it reads the payload again
+      # under the job's lock, which a replacement holds while it writes.
+      module ConcurrencyLocks
+        private
+          def record_concurrency_lock(**)
+            self.arguments = self.class.lock.find(id).arguments if created_replacing?
+            super
+          end
+      end
+
+      # A replacing job releases its key and reads its payload again before Active
+      # Job deserializes it, so the run has every replacement admitted before the
+      # release. Raises like super, into a failed execution.
+      module ReplacingExecution
+        private
+          def execute
+            job.start_replacing_run if job.created_replacing?
+            super
+          rescue Exception => e
+            ClaimedExecution::Result.new(false, e)
           end
       end
 
@@ -100,6 +126,7 @@ module SolidQueue
 
         included do
           validate :ensure_job_class_not_collecting
+          validate :ensure_job_class_not_replacing
           validate :ensure_job_class_not_debounced
         end
 
@@ -112,6 +139,13 @@ module SolidQueue
             end
           end
 
+          # A tick that replaces would record the open job again, and roll back its replacement
+          def ensure_job_class_not_replacing
+            if class_name.present? && job_class&.try(:coalesce_replace?)
+              errors.add :class_name, :replacing, message: "can't be a job that uses `coalesce` with `on_conflict: :replace`"
+            end
+          end
+
           # A tick passes no time, so the window applies, and a tick that joins pushes
           # the job back. With an interval shorter than the window it would never run.
           def ensure_job_class_not_debounced
@@ -127,6 +161,8 @@ module SolidQueue
         SolidQueue::Job.prepend Failing
         SolidQueue::Job.prepend Finishing
         SolidQueue::Job.prepend ConcurrencyConflicts
+        SolidQueue::Job.prepend ConcurrencyLocks
+        SolidQueue::ClaimedExecution.prepend ReplacingExecution
         [ ReadyExecution, ScheduledExecution, BlockedExecution, FailedExecution ].each { |execution| execution.singleton_class.prepend BulkDiscarding }
         SolidQueue::RecurringTask.include RecurringValidation
       end

data/lib/solid_queue/coalesce/version.rb

@@ -1,5 +1,5 @@
 module SolidQueue
   module Coalesce
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue-coalesce
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - David Cristofaro
@@ -135,6 +135,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: solid_queue-rate_limit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.1
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
@@ -208,7 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.20
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Dedupe, debounce and batch Solid Queue jobs.
 test_files: []