riverqueue 0.12.0 → 0.14.0

data/docs/README.md

@@ -1,6 +1,6 @@
-# River client for Ruby [![Build Status](https://github.com/riverqueue/riverqueue-ruby/workflows/CI/badge.svg)](https://github.com/riverqueue/riverqueue-ruby/actions) [![Gem Version](https://badge.fury.io/rb/riverqueue.svg)](https://badge.fury.io/rb/riverqueue)
+# River client for Ruby [![Build Status](https://github.com/riverqueue/river/actions/workflows/ruby.yaml/badge.svg)](https://github.com/riverqueue/river/actions/workflows/ruby.yaml) [![Gem Version](https://badge.fury.io/rb/riverqueue.svg)](https://badge.fury.io/rb/riverqueue)
 
-A Ruby client for [River](https://github.com/riverqueue/river), packaged in the [`riverqueue` gem](https://rubygems.org/gems/riverqueue). It inserts and works jobs using River's canonical database schema and state machine, so Ruby and Go clients can safely share a River database. Separate queues are recommended when each language recognizes different job kinds.
+A Ruby client for [River](https://github.com/riverqueue/river), packaged in the [`riverqueue` gem](https://rubygems.org/gems/riverqueue). It inserts and works jobs using River's canonical database schema and state machine, so Ruby and River clients in other languages can safely share a River database. Separate queues are recommended when each language recognizes different job kinds.
 
 ## Installation
 
@@ -26,9 +26,9 @@ its uniqueness and notification capabilities.
 ## Schema and migrations
 
 Run migrations before inserting jobs or starting workers. The bundled `river`
-command uses Go's canonical PostgreSQL and SQLite migrations; no Go installation
-is needed. After installing a River driver and its database adapter, create your
-application's PostgreSQL database and run:
+command uses River's canonical Postgres and SQLite migrations, bundled with the
+gem. After installing a River driver and its database adapter, create your
+application's Postgres database and run:
 
 ```sh
 export DATABASE_URL=postgres://localhost/my_app
@@ -39,8 +39,8 @@ bundle exec river migrate-up
 ```
 
 `migrate-up` applies all pending migrations and is safe to rerun: already-applied
-versions are skipped, including migrations applied by Go. `--dry-run` previews
-the plan without changing the database. Pass `--database-url URL` to override
+versions are skipped, including migrations applied by other River clients.
+`--dry-run` previews the plan without changing the database. Pass `--database-url URL` to override
 `DATABASE_URL`.
 
 For SQLite, ensure the parent directory exists, then use a SQLite URL:
@@ -57,7 +57,7 @@ both are in your bundle.
 For River Pro, install `riverqueue-pro`, apply the main migrations above, then
 run `bundle exec river migrate-up --line pro` against the same database.
 
-See the [migration guide](migrations.md) for the Ruby API, PostgreSQL schemas,
+See the [migration guide](migrations.md) for the Ruby API, Postgres schemas,
 target versions, downgrade precautions, and existing SQLite Pro installations.
 Test schema snapshots under `spec/support` are test-only and must not be used
 to provision production databases.
@@ -110,12 +110,37 @@ Job arguments must respond to `#kind` and `#to_json`. They may also return defau
 Use strings for `#kind` definitions, and symbols for identifiers such as queues,
 states, periodic job IDs, and resumable step names. Both forms are accepted.
 Persisted job attributes and JSON object keys remain strings, preserving
-compatibility with Go clients.
+compatibility with River clients in other languages.
 Examples omit parentheses on simple calls and `do...end` blocks, retaining them
 for nested expressions and `{ ... }` blocks where they make binding clear.
 
 ## Core features
 
+### Block workers
+
+Pass a kind and a block to `Workers#add` to define a worker inline:
+
+```ruby
+workers = River::Workers.new
+workers.add(:message) do |job|
+  puts "Message: #{job.args.fetch("message")}"
+end
+
+# With client configured to use this registry and the ruby queue:
+client.insert River::JobArgsHash.new(:message, message: "Hello!"), queue: :ruby
+```
+
+Pass this registry as `workers:` in `River::Config`. The kind accepts a string
+or symbol and must match the inserted job's kind. The block receives a
+`River::Job` and uses the client's retry and timeout policies. Returning normally
+completes the job; the block's return value is ignored. Raise exceptions to fail,
+cancel, or snooze work as with a worker class. Optionally use `job.output =` to
+persist a result. Aliases are supported through `aliases:` as for other workers.
+Supply a worker or a block, not both. Existing procs or methods can be passed as
+the block with `&`.
+The same block may run concurrently for multiple jobs, so any captured mutable
+state must be safe to share across threads.
+
 ### [Accessing the client from workers](https://riverqueue.com/docs/context-client)
 
 Every running `River::Job` exposes the client that claimed it. Workers can use
@@ -133,6 +158,12 @@ end
 
 Insertion keywords control the queue, priority, maximum attempts, schedule,
 tags, metadata, and uniqueness of a job. Priority `1` is highest.
+`max_attempts` must be between 1 and 32,767 on every database.
+An explicit `state` must be `:available`, `:pending`, or `:scheduled` (strings
+are also accepted). Other states raise `ArgumentError` before any jobs are
+inserted, including when an invalid state appears in a batch. Without an
+explicit state, jobs are available immediately or scheduled when `scheduled_at`
+is in the future.
 
 ```ruby
 result = client.insert(args,
@@ -153,8 +184,8 @@ For simple jobs, `River::JobArgsHash.new(:kind, hash)` avoids defining an argume
 
 ### [Transactional enqueueing](https://riverqueue.com/docs/transactional-enqueueing)
 
-Insertion hooks and middleware execute inside the insertion transaction. If
-they raise, their database writes and the enqueue roll back together. PostgreSQL
+Insertion hooks and middleware execute inside the insertion transaction, so
+their database writes and the enqueue commit or roll back together. Postgres
 insert notifications are delivered only when the surrounding transaction commits.
 
 Inserts automatically join a transaction opened through the same Active Record connection or Sequel database object. A rollback also rolls back the job:
@@ -175,6 +206,62 @@ end
 
 The equivalent works inside `ActiveRecord::Base.transaction` with the Active Record driver.
 
+River calls inside an open transaction run in that transaction and open no
+savepoint of their own. If a River call raises, it may leave partial changes,
+so roll back the transaction. To recover from the error and continue the
+transaction, wrap the call in your own savepoint, such as
+`DB.transaction(savepoint: true)` or
+`ApplicationRecord.transaction(requires_new: true)`.
+
+### Transactional completion
+
+Call `job.client.job_complete_tx(job)` inside a transaction to commit application
+writes and job completion together (the equivalent of Go's `JobCompleteTx`):
+
+```ruby
+class FulfillOrderWorker
+  def work(job)
+    DB.transaction do
+      DB[:orders].where(id: job.args.fetch("order_id")).update(fulfilled: true)
+      job.output = {fulfilled: true}
+      job.client.job_complete_tx(job)
+    end
+  end
+end
+```
+
+With Active Record 7.2 or later, use it inside an `ApplicationRecord.transaction` block. As
+with insertion, the transaction must use the driver's connection on the same
+thread. No explicit transaction argument is needed. Calling `job_complete_tx`
+without an active transaction on that connection raises `River::Error` without
+changing the job.
+
+Sequel 5.20 or later is required so transaction callbacks respect savepoints.
+
+`job_complete_tx` accepts the running `River::Job` passed to the worker and returns
+an updated `River::JobRow`, leaving the original job unchanged. Set output and
+metadata before calling it so they're included in the transaction. A missing
+job raises `River::NotFoundError`; a pending cancellation raises
+`River::JobCancelError`, allowing the transaction to roll back.
+The supplied job must still belong to the current attempt; a stale worker cannot
+complete a replacement attempt.
+Metadata added afterward, including persisted logs, is saved separately when
+the worker finishes, provided the completed attempt has not been retried.
+
+Make completion the last operation in the transaction and let the transaction
+commit before returning from `work`. Propagate errors that roll back the
+transaction so River retries the job. If you swallow a rollback and return
+successfully, River completes the job normally. Once completion commits, later
+worker errors cannot retry or cancel the job. River emits `:job_completed` when
+the worker finishes, and skips its usual finalization hooks for the already
+completed job.
+If the completed row is deleted before the worker finishes, River emits the
+completion event using the snapshot retained when the transaction committed.
+
+If the job is manually retried before the original worker finishes, that worker
+leaves the replacement attempt untouched and does not emit a completion event
+for it.
+
 ### [Bulk insertion](https://riverqueue.com/docs/inserting-many-jobs)
 
 `#insert_many` inserts a batch atomically and returns one `River::JobInsertResult` per input. Use `River::InsertManyParams` when jobs need different options:
@@ -224,7 +311,7 @@ order affect the hash even when the decoded JSON is equivalent.
 
 ### [Reliable execution and stuck jobs](https://riverqueue.com/docs/reliable-workers)
 
-Claims and state transitions are atomic in the database. If a process disappears while working, the elected maintenance client rescues stale running jobs after an hour, retrying or discarding them according to their attempt count. `attempted_by`, attempt errors, and final state remain in the canonical River row for inspection by Ruby, Go, or River UI.
+Claims and state transitions are atomic in the database. If a process disappears while working, the elected maintenance client checks for stale running jobs after an hour, retrying or discarding them according to their attempt count. Rescue respects longer client and worker timeouts; disabling a job's timeout also disables automatic timeout-based rescue for it. Cancellation requests still take precedence. Keep worker registrations and timeout configuration consistent across maintenance clients. `attempted_by`, attempt errors, and final state remain in the canonical River row for inspection by any River client or River UI.
 
 ### [Job retries](https://riverqueue.com/docs/job-retries)
 
@@ -243,12 +330,18 @@ config = River::Config.new(
 ```
 
 Use `client.job_retry(job_id)` to make a non-running job available immediately.
+This clears its previous cancellation request. Once a job has reached 32,767
+attempts, requesting another retry raises `ArgumentError` without changing it.
 
 A worker may implement `retry?(job, error)` and return false to discard a
 reported error immediately, without reducing the attempt budget used for crash
 recovery. The Rails integration uses this to let Active Job own application retries.
+Jobs claimed and finished by batch extensions honor the registered worker's
+`retry?` and `next_retry` hooks too, including workers registered as classes.
 If a retry hook or policy raises, River logs the callback error and falls back to
 retrying with the default backoff. The original work error is still recorded.
+Stuck-job rescue also falls back per job when a retry policy raises or returns
+an invalid time, allowing other rescues and cleanup to continue.
 
 ### [Error handling and timeouts](https://riverqueue.com/docs/error-handling)
 
@@ -310,6 +403,9 @@ config = River::Config.new(queues: {
 ```
 
 Queues may also be added and removed at runtime with `client.queue_add(name, config)` and `client.queue_remove(name)`.
+Queue removal stops fetching and keeps observing cancellation requests until its
+active jobs finish. Removing a queue from one of its own workers raises
+`ThreadError`, because that worker cannot wait for itself to finish.
 
 ### [Pausing queues](https://riverqueue.com/docs/pausing-queues)
 
@@ -324,6 +420,9 @@ client.queue_resume "*"
 ```
 
 Use `queue_get`, `queue_list`, and `queue_update` to inspect queues and attach metadata.
+Pause and resume events contain a snapshot of each affected queue. Wildcard
+operations publish events for every affected queue; size subscription buffers
+to accommodate the number of events you expect to receive.
 
 ### Rails and Active Job
 
@@ -340,6 +439,11 @@ the job is due, not during registration. A reusable callable can be passed as
 `constructor:` instead; don't supply both. Core periodic schedules live in the
 client process; River Pro adds durable schedules.
 
+A started client can produce periodic jobs with `queues: {}` while other clients
+consume them. Jobs added through `client.periodic_jobs` also start maintenance
+when needed. Periodic registration requires leader election to be enabled,
+including jobs registered after startup.
+
 ```ruby
 cleanup = River::PeriodicJob.new(
   id: :cleanup,
@@ -360,6 +464,10 @@ registrations and returns the bundle.
 `add_many` registers a batch atomically: duplicate IDs or invalid schedules leave
 the registry unchanged.
 
+Inserted jobs carry `periodic: true` in metadata and, when the registration has
+an ID, `river:periodic_job_id`. Constructor options and application metadata are
+preserved.
+
 Schedules can be callbacks (`schedule: ->(now) { now + 300 }`) or objects
 implementing `next(time)`. They must return a `Time` strictly after the supplied
 time; they do not execute the job themselves. A schedule that raises at runtime
@@ -376,12 +484,15 @@ cleanup = River::PeriodicJob.new(
 
 `PeriodicCron` parses once and loads Fugit only when constructed. Fugit is not
 a runtime dependency of the River gem. The timezone defaults explicitly to UTC;
-provide it through `timezone:`, not inside the expression. Five-field cron,
-optional seconds, and aliases such as `@daily` use Fugit's syntax. Results are
-UTC `Time` objects. Local calendar times follow Fugit's daylight-saving rules;
-nonexistent spring-forward times are skipped. Test ambiguous fall-back times
-for your schedules. Cron does not change core scheduling durability or replay
-missed occurrences after downtime.
+set `timezone:` or use a `CRON_TZ=` / `TZ=` prefix, which takes precedence.
+Five-field cron, optional seconds, and aliases such as `@daily` use Fugit's
+syntax; `?` is also accepted as a wildcard. `@every` accepts durations such
+as `1h30m`, built from `ns`, `us`, `ms`, `s`, `m`, and `h` units, rounded down
+to whole seconds with a one-second minimum. Unlike `PeriodicInterval`, these intervals align to whole-second boundaries.
+Results are UTC `Time` objects. Nonexistent spring-forward times are skipped;
+both occurrences of a repeated fall-back time are scheduled. See
+[conformance differences](conformance.md) before sharing schedules across
+languages. Cron does not replay missed occurrences after downtime.
 
 For a one-time date, insert a job with
 `client.insert(args, scheduled_at: Time.utc(2026, 9, 20, 9))` instead of registering
@@ -389,7 +500,7 @@ a periodic job. This stores the scheduled job immediately in the database.
 
 ### [Resumable jobs](https://riverqueue.com/docs/resumable-jobs)
 
-Long jobs can checkpoint idempotent steps and cursor progress. On retry, River skips completed steps and resumes a cursor step from its last recorded value using the same metadata format as Go.
+Long jobs can checkpoint idempotent steps and cursor progress. On retry, River skips completed steps and resumes a cursor step from its last recorded value using River's shared metadata format.
 
 ```ruby
 def work(job)
@@ -451,7 +562,7 @@ end
 ### Job-persisted logging
 
 Add `River::JobPersistedLogging::Plugin` to save worker logs with each job attempt,
-using the same `metadata["river:log"]` format as Go's `riverlog` and River UI. This
+using the shared `metadata["river:log"]` format that River UI displays. This
 is a core feature; it does not require Pro or additional migrations.
 
 ```ruby
@@ -527,13 +638,16 @@ A plugin may implement any combination of these methods:
 | Hook       | `insert_begin(params)`           | Before each job is inserted; `params` may be modified.                                       |
 | Hook       | `insert_end(result)`             | After each job is inserted.                                                                  |
 | Hook       | `work_begin(job)`                | After a job is claimed, immediately before its worker runs.                                  |
-| Hook       | `work_end(job, error)`           | After the worker returns or raises; `error` is `nil` on success.                             |
+| Hook       | `work_end(job, error)`           | After the worker returns or raises a `StandardError`; returns the attempt's error or `nil`. |
 | Hook       | `job_finalize(job, state)`       | Before successful finalization; returning `:delete` deletes the job instead of retaining it. |
 | Middleware | `insert_many(params, operation)` | Around one insertion call; `params` is an array even for `Client#insert`.                    |
 | Middleware | `work(job, operation)`           | Around the work hooks and worker for one claimed job.                                        |
 
 A single plugin can provide both styles. For example, it might use
 `insert_begin` to add metadata and `work` to time the complete work operation.
+After insertion hooks run, each job must still have an initial state of
+`available`, `pending`, or `scheduled`. Invalid states roll back the batch
+and any database writes made by its hooks.
 
 ```ruby
 class TimingPlugin
@@ -551,10 +665,33 @@ end
 config = River::Config.new(plugins: [AuditPlugin.new, TimingPlugin.new])
 ```
 
-Plugins earlier in the list are the outermost wrappers. Begin callbacks run in
-configuration order, while `insert_end` callbacks run in reverse order. In
-effect, work execution is nested as: middleware before, `work_begin`, worker,
-`work_end`, middleware after.
+Plugins earlier in the list are the outermost wrappers. Begin callbacks and
+`work_end` callbacks run in configuration order, while `insert_end` callbacks
+run in reverse order. In effect, work execution is nested as: middleware before,
+`work_begin`, worker, `work_end`, middleware after.
+
+Each `work_end(job, error)` receives `nil` on success or the worker's exception
+on failure. Return `error` to preserve that outcome, a different exception to
+replace it, or `nil` to clear a failure. Each subsequent end hook receives the
+previous hook's return value. After all end hooks run, River raises the final
+error through the middleware, or completes the operation if it is `nil`.
+Returning `River.job_cancel(...)` or `River.job_snooze(...)` selects the
+corresponding cancellation or snooze behavior.
+
+An observing hook must explicitly return its incoming error:
+
+```ruby
+def work_end(job, error)
+  Metrics.record_attempt(job.kind, error: error)
+  error
+end
+```
+
+If a `work_begin` hook raises, River skips the worker and all end hooks. If an
+end hook raises instead of returning an error, it stops the end-hook chain and
+propagates that exception through the middleware. Fatal exceptions outside
+`StandardError` also bypass end hooks. Use middleware with `ensure` for cleanup
+that must run when hooks or work raise.
 
 ### [Subscriptions](https://riverqueue.com/docs/subscriptions)
 
@@ -604,7 +741,11 @@ client.job_delete_many states: [:cancelled]
 
 Reusable `JobListParams` and `JobUpdateParams` objects are also accepted as
 positional arguments, instead of keywords. For updates, omitted fields remain
-unchanged; an explicit `nil` clears a nullable field.
+unchanged; an explicit `nil` clears a nullable field. Metadata must be a Hash;
+use `metadata: {}` to clear it. Values inside the Hash may be `nil`.
+Updated `max_attempts` must be between 1 and 32,767; `attempt` must be between
+0 and 32,767. Claims cap the attempt counter at 32,767 so an administratively
+requeued job cannot prevent other jobs from being claimed.
 
 Bulk deletion requires at least one filter and never deletes running jobs.
 Metadata filters compare complete JSON values at each supplied top-level key,
@@ -647,11 +788,35 @@ config = River::Config.new(
 ```
 
 A custom service implements `run(client, driver, now)` and runs only while this client holds leadership.
+Service errors are logged without interrupting other services, stuck-job rescue,
+or cleanup. A failed service is retried on the next scheduled maintenance pass.
+
+Call `client.request_resign` to ask the current maintenance leader to resign.
+The leader releases its lease and briefly delays reelection so another client
+can take over. The request joins the caller's transaction and is delivered only
+on commit.
 
 On SQLite, the leader also removes notification outbox entries older than five
-minutes in bounded batches. Cancellation requests write Go-compatible control
-notifications in the same transaction as the job update; Ruby workers continue
-to observe cancellation through polling.
+minutes in bounded batches.
+
+### Notifications
+
+Started clients receive job insertion, queue control, cancellation, and
+leadership notifications. Postgres uses one dedicated LISTEN connection per
+started client, separate from the application's connection pool. SQLite polls
+the notification outbox with an independent cursor for each client. Inserts,
+scheduled jobs becoming available, and manual retries wake workers promptly.
+
+The receiver starts before workers and stays active during graceful shutdown.
+Startup fails if the initial subscription fails; an established receiver retries
+after connection errors and refreshes persisted state on reconnect. Normal job
+and queue polling also remains active.
+
+Set `poll_only: true` in `River::Config` to disable receiving notifications, for
+example when connecting through a proxy that cannot support LISTEN. Job, queue,
+and cancellation changes are then observed at the polling interval, and
+`request_resign` is not received. Backends without native notification support,
+such as Yugabyte with LISTEN/NOTIFY disabled, use polling automatically.
 
 ### [Renaming job kinds](https://riverqueue.com/docs/renaming-jobs)
 
@@ -682,6 +847,13 @@ The Ruby configuration file must return an unstarted client. The following clien
 methods are for applications managing their own runtime lifecycle:
 
 `client.stop` stops fetching and waits for active jobs to finish. `client.stop_and_cancel` interrupts active worker threads and returns their jobs to `available` without consuming the interrupted attempt.
+While draining, the client continues receiving and polling for cancellation requests from
+other clients, including for workers with no timeout. Transient polling errors
+are retried until the active attempts finish.
+
+Blocking stop calls from the client's own workers or other runtime threads
+raise `ThreadError`. A worker can request shutdown with `client.stop(wait: false)`
+and then finish its work.
 
 Use `client.stop(wait: false)` to request stop and return immediately without
 interrupting active workers. Call `client.stop` later to wait for draining and
@@ -705,6 +877,11 @@ Load River and worker definitions in the main Ractor before spawning others. Eac
 
 Database drivers, Active Record, Sequel, and optional dependencies such as Fugit still need their own Ractor compatibility. Job timeouts also depend on Ruby and the `timeout` gem: the test suite exercises them on Ruby 4 with `timeout` 0.6.1; tests on older Rubies disable job timeouts. `WorkerRunner` handles process-wide signals and must run on the main thread of the main Ractor.
 
+Ruby 3.3 and 3.4 can deadlock while scheduling threads inside Ractors, even
+without River ([Ruby bug #20905](https://bugs.ruby-lang.org/issues/20905), fixed
+in Ruby 4). The test suite skips the producer/maintenance lifecycle test on
+those versions; insertion and synchronous worker checks still run.
+
 Ruby 4.0.2 with `timeout` 0.6.1 can intermittently deadlock during VM shutdown
 while terminating Ractors and their timeout helper threads, even after work
 finishes successfully. This reproduces without River. Tests bypass that shutdown
@@ -714,7 +891,7 @@ limitations are resolved.
 
 ## RBS and type checking
 
-The gem bundles [RBS files](https://github.com/riverqueue/riverqueue-ruby/tree/master/sig) for tools such as [Steep](https://github.com/soutaro/steep) and other RBS-compatible type checkers.
+The gem bundles [RBS files](https://github.com/riverqueue/river/tree/master/ruby/sig) for tools such as [Steep](https://github.com/soutaro/steep) and other RBS-compatible type checkers.
 
 ## Drivers
 
@@ -748,17 +925,17 @@ Minitest integrations are optional and explicitly loaded.
 
 River Pro is kept in the separate, privately distributed `riverqueue-pro` gem, so possession of that package is the access boundary. It is not included in the MPL-2.0 core gem. Its implementation and documentation live in the private `riverqueue-ruby-pro` repository; see that repository's README for configuration and feature examples.
 
-## Current differences from the Go client
+## Current limitations
 
-The shared PostgreSQL insert-only conformance profile is exercised through both
-SQL drivers. Full runtime, SQLite, and multi-engine conformance remain in
-progress; see the [conformance status and differences](../conformance/README.md).
+Ruby checks shared fixtures for unique keys, cron, snooze counters, and
+protocol values.
+See [conformance coverage and differences](conformance.md); this is not yet a
+full mixed-language runtime suite.
 
 The Ruby client does not currently provide dedicated OpenTelemetry/metrics
 integrations or
 transactional job completion alongside application writes. Plugins and
-subscriptions provide integration points for telemetry. Job execution uses Ruby
-worker objects rather than Go's work-function API.
+subscriptions provide integration points for telemetry.
 
 ## Development
 

data/docs/conformance.md

@@ -0,0 +1,72 @@
+# Ruby conformance
+
+Ruby reads fixtures generated from this checkout's Go implementation, alongside
+Rust and JavaScript. From the repository root:
+
+```sh
+make -C ruby install
+make test/ruby/conformance
+```
+
+This generates `conformance/testdata/` and runs `ruby/spec/conformance_spec.rb`.
+No Postgres server, pinned upstream checkout, protocol adapter, or separately
+maintained golden files are needed. Missing fixtures fail with instructions to
+regenerate them. The regular Ruby suite includes these checks too.
+
+The fixture checks cover:
+
+- All unique-key cases, including typed-only cases, raw JSON tokens, selected
+  fields, periods, queues, and state masks.
+- Job state names and unique bits, attempt-error encoding/decoding, retry bounds,
+  and all six shared metadata keys, including actual output, rescue, periodic,
+  unique insertion, and resumable-step persistence.
+- All snooze-counter fixtures through real worker attempts and both SQL drivers.
+- Cron occurrences, named zones, daylight-saving transitions, interval schedules,
+  and invalid expressions, with the Ruby API differences below checked explicitly.
+- Insertion, cancellation, queue pause/resume/metadata, and leadership resignation/request
+  notification encoding through both SQL drivers, using in-memory SQLite and
+  the bundled canonical migrations.
+
+The Ruby workflow runs on Ruby changes. The shared Conformance workflow also
+runs these tests when Go code changes. The ordinary driver suites retain
+Postgres notification delivery/commit-ordering tests and shared Postgres /
+SQLite insertion, transaction, uniqueness, and worker tests.
+
+This replaces the old `insert-only-v1` adapter and its pinned external harness.
+It checks shared data formats, not live mixed-language worker execution. Adapter
+handshake and request-schema tests were specific to that removed harness; their
+protocol is not part of the Ruby API.
+
+## Coverage gaps and API differences
+
+Ruby consumes Postgres LISTEN events and the SQLite notification outbox. The
+ordinary driver suites exercise insert wakeups, cancellation while draining,
+queue pause/resume, and leadership handoff on `request_resign` through both
+backends and both SQL drivers. They also check commit ordering, rollback,
+independent listeners, startup failures, and recovery after listener failures.
+The fixture target checks wire formats; live mixed-language worker execution
+remains outside its scope.
+
+Shared snooze-counter fixtures cover non-negative integers and absent counters.
+Recovery from other JSON values is implementation-specific. Ruby's shared driver
+tests cover its lenient conversion rules separately on Postgres and SQLite.
+
+Cron retains Ruby's existing Fugit extensions: six fields with seconds, Sunday
+as 7, hour 24, and descending ranges. These four expressions are accepted in
+Ruby and rejected in Go; the fixture suite explicitly asserts the difference.
+Fugit rejects impossible calendar dates at construction instead of returning
+Go's zero time. Ruby's default calendar zone remains UTC; tests explicitly pass
+the reference time's fixed offset to model Go's time-location API. `CRON_TZ=` /
+`TZ=` prefixes, `?`, and `@every` duration rounding now follow Go for the shared
+fixtures. No new dependencies were added.
+
+Selected unique fields use `by_args: [:field, [:nested, :field]]`, rather than Go
+struct tags. Dotted string keys are literal. Cross-language unique keys require
+the same encoded argument values, including escaping, numeric tokens, and
+nested ordering; Ruby does not override the application's JSON serialization.
+
+Transactions are connection-scoped blocks. Workers use exceptions and thread
+interruption. List cursors encode the selected field explicitly. Historical
+error timestamps accept Ruby's `Time.parse` formats, and metadata must decode
+to an object. Live interoperability across these boundaries is not covered by
+the fixture target.

data/docs/migrations.md

@@ -1,8 +1,8 @@
 # Schema migrations
 
-River Ruby includes a migration API and the `river` command. Neither needs
-Go installed. The gems bundle byte-for-byte copies of the PostgreSQL and SQLite
-SQL from Go's River drivers, pinned to release v0.48.0 through migration 008;
+River Ruby includes a migration API and the `river` command. The gems bundle
+byte-for-byte copies of River's canonical Postgres and SQLite migration SQL,
+pinned to release v0.48.0 through migration 008;
 only the upstream schema template placeholders are substituted when executing
 them.
 
@@ -24,7 +24,7 @@ bundle exec river migrate-up --database-url sqlite://storage/river.sqlite3
 
 `DATABASE_URL` supplies the URL when `--database-url` is omitted. ActiveRecord
 uses `sqlite3:` URLs instead of Sequel's `sqlite:` URLs. To target an existing
-PostgreSQL schema, pass `--schema jobs`; otherwise the connection's current
+Postgres schema, pass `--schema jobs`; otherwise the connection's current
 schema is used. Schema names must be simple SQL identifiers. SQLite always
 uses its main schema.
 
@@ -52,22 +52,22 @@ migrator.migrate(dry_run: true, target: 8)
 migrator.migrate(direction: :down) # One version; no interactive confirmation.
 ```
 
-The API accepts either driver and optionally `schema:` for PostgreSQL. `migrate`
+The API accepts either driver and optionally `schema:` for Postgres. `migrate`
 returns the migration records applied (or planned in dry-run mode), with their
 version, name, and original up/down SQL. Each version's SQL and history update
 commit in their own transaction. A failing version rolls back while earlier
 versions remain committed, so rerunning resumes safely. Do not wrap the migrator
-in an application transaction: some PostgreSQL changes require a real commit
+in an application transaction: some Postgres changes require a real commit
 before the next version can run.
 
 An up migration targeting an already-applied version does nothing, even when
 newer migrations are pending.
 
-## Go compatibility and Pro
+## Compatibility and Pro
 
-The migrator reads and writes Go's `river_migration` history, including the
-legacy pre-version-5 format. Either language can continue from the other's
-applied versions. Unknown newer versions and gaps in history cause an error
+The migrator reads and writes the `river_migration` history shared by all River
+clients, including the legacy pre-version-5 format. Any River client can
+continue from versions applied by another. Unknown newer versions and gaps in history cause an error
 rather than guessing what SQL to run. It does not baseline an existing schema
 that has no River migration history.
 
@@ -75,7 +75,7 @@ Pro SQL is distributed only inside `riverqueue-pro`, not the public core gem.
 SQLite main migration 008 rebuilds `river_job` with `AUTOINCREMENT` so deleted
 job IDs are not reused. Its upgrade and downgrade refuse to run while Pro's
 workflow/sequence schema is installed; coordinate that upgrade with Pro before
-running it on an existing Pro database. PostgreSQL migration 008 is a no-op.
+running it on an existing Pro database. Postgres migration 008 is a no-op.
 
 Migrate main first, then Pro:
 
@@ -92,30 +92,27 @@ River::Pro::Migrator.new(driver).migrate
 ```
 
 Remove other migration lines before downgrading main. Run only one migration
-process at a time across languages. Ruby migrators take a PostgreSQL advisory
+process at a time across languages. Ruby migrators take a Postgres advisory
 lock per schema; SQLite takes a write lock per version and checks for concurrent
-history changes. These are not shared locks with Go's migration runner.
+history changes. These locks are not shared with other River clients' migration runners.
 
 ## Updating the bundled SQL
 
-`migration/manifest.json` records the upstream commit and each file's SHA-256.
-Synchronize or verify the public migrations against a local Go checkout:
+`migration/manifest.json` records each canonical file's SHA-256. From `ruby/`,
+synchronize or verify against the canonical migrations in this same checkout:
 
 ```sh
-ruby scripts/sync_migrations.rb ../river
+ruby scripts/sync_migrations.rb
 make verify
-make verify RIVER_PATH=/path/to/river
 ```
 
-`make verify` defaults to `../river` and checks SQL contents, filenames, the
-license, and the manifest's checksums and source revision. CI fetches the public
-River repository at that recorded revision and runs the same check; it does not
-require a sibling checkout or access to the private Pro repository.
+Verification checks SQL contents, filenames, license, and manifest checksums.
+CI uses the same working-tree comparison; no separate checkout is needed.
 
 Pro migrations have their own manifest and sync script in the private
 `riverqueue-ruby-pro` repository. Run that repository's `make verify` against
-the Go Pro checkout; the public sync script handles only the main migrations.
+the River Pro checkout; the public sync script handles only the main migrations.
 
 Review the upstream changes and run the complete test matrix before publishing.
 Do not edit the copied SQL independently. Upstream changes are bundled in gem
-releases; users do not need the Go repositories or network access at runtime.
+releases; users do not need the upstream repositories or network access at runtime.

data/docs/testing.md

@@ -1,6 +1,6 @@
 # Testing River jobs
 
-Testing helpers ship in `riverqueue`. They use your real PostgreSQL or SQLite
+Testing helpers ship in `riverqueue`. They use your real Postgres or SQLite
 database through either driver; there is no fake queue, global testing mode,
 implicit migration, or automatic cleanup. Require them explicitly: