stablemates-workhorse 0.0.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0ccf89624e70f05719adf1c51708ea2225f3e572f9f76feefa9ed1bbe70d931
-  data.tar.gz: d0edc384cabeedd7e279d2d5a34a13eabc55617bf626daaaac5fb739fee56b08
+  metadata.gz: 98c5582b19c14aaf69dd9b317684c9a5e49a5508caf5759b79894fbe78c54146
+  data.tar.gz: 6f9a14b8dff61da2cadacc25f792c44a8b25281877b12bb47530a296b5a1e9e0
 SHA512:
-  metadata.gz: 4010e3ad425e862f212588b5b2b60b43bf9f7cab7b35203ba8fd470d2534b839419977474ec339dd9d9354458ba5f032329a6b2edcc0cd83c49c0636cdc6c3e4
-  data.tar.gz: 73c8d6c59994652de82b8539e195308019e729607cfee18f84a1d1c22332ef40ffa518c61bb3e9820a6f3aefaba7cae80a0fdc45a266505f2e1eb4a853cf7c70
+  metadata.gz: 98805ebb4ddc387026073a530960c1494ea7fbfac0a294829b1152b0f300dbb551d1ae4c944a87fdf698e6a0debd96ddf825e55444c8dffb9b584beb74053e05
+  data.tar.gz: 81fef1e8bf1c9e5850b031aa5ac697a93b85ecbda2ae63687b60dfd6c2d821f08304b45e816dafadeea6105ef12820734e81086f3543bbfb5bb9bd7f857c9061

data/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Ruby changelog
+
+`stablemates-workhorse` gem versions and release notes live here. The gem carries the version the
+other SDKs carry, because every tag names one release of all of them.
+
+## 0.6.0 — 2026-10-02
+
+The npm packages, Python distribution, Go module, Rust crate, and Ruby gem release from one source commit.
+
+Requires **schema v43**, Ruby **3.3** or newer, and PostgreSQL **15** or newer.
+
+- The gem needs schema version 43 or later. The SDK compatibility floor is schema version **43**,
+  and the final schema version is **52**. The migrations since 0.5.0 only add, so the upgrade is a
+  rolling deployment: run `workhorse schema migrate` before any new process starts. The
+  [root changelog](../CHANGELOG.md) lists the SQL fixes. Each takes effect when its migration commits, and version 52
+  includes them all.
+- An installation that runs cold export stops its exporters across migration 0052. That migration
+  repairs the export ledger, but it cannot stop an upload already in flight. Upgrade in this order:
+
+  1. Stop every cold exporter, and let each finish its object and manifest uploads.
+  2. Keep cold export enabled, so retention keeps waiting for the export.
+  3. Run `workhorse schema migrate`.
+  4. Restart the exporters after the migration commits.
+
+  An installation that never enabled cold export needs no extra step. The
+  [cold export guide](../docs/guides/335-cold-export.md#a-day-is-a-utc-day) explains the repair.
+
+- A handler result PostgreSQL cannot store now fails only its task. jsonb refuses a NUL character
+  and an unpaired surrogate. Such a result used to reach the completion statement, whose refusal
+  ended `run` and left the task leased. The worker now fails the attempt under the task's retry
+  policy with an `ArgumentError`. Its message names the task type and carries no part of the value.
+  On the fast tier the other members of a completion batch still complete. A database error during
+  completion still ends `run`.
+- `Queue#sync_schedules` applies each task type's current contract, read from PostgreSQL, before
+  the write. A payload that fails the schema raises `ContractValidationError` and writes nothing. A
+  valid definition stores the contract version, its size limits, and its redaction keys.
+- Add the `Queue` client: `enqueue` and `enqueue_many` with every client enqueue option,
+  cancellation, signal and human wait delivery, queue health, and schedule and contract
+  synchronization. `sync_concurrency_policies`, `sync_rate_limit_policies`, and `sync_budgets`
+  replace a namespace's definitions, and the list methods read them back.
+- Durations, including a `RateLimit` interval, are finite Numeric seconds. The client refuses a
+  value outside a protocol bound with `ArgumentError` before it sends any statement.
+- Contract schemas are checked against the draft 2020-12 meta-schema. The contract profile rejects
+  `pattern` and `patternProperties` at any depth with `ArgumentError`, as every SDK does
+  ([ADR 0039](../docs/decisions/0039-use-a-restricted-json-schema-contract-profile.md)). Check a
+  string's shape in handler code instead. A `$ref` must point at a subschema, so it cannot reach a
+  schema hidden in `default` or `examples`; any other reference raises `ArgumentError` with
+  `<path>.$ref must point at a subschema of the contract`, including a pointer that encodes `/` as
+  `%2F`.
+- **Breaking: a contract version that another SDK's 0.5 release synced with `pattern` or
+  `patternProperties` does not compile in this gem.** Upgrade in this order:
+  1. Find each contract version that uses either keyword, or a `$ref` that points outside a
+     subschema.
+  2. Publish a new version without either keyword, and move `currentVersion` to it.
+  3. Let tasks that hold the old version finish before you run Ruby workers. A worker checks a
+     task's result against the version the task holds. If that version's result schema uses either
+     keyword, completing the task fails the attempt with `ArgumentError`, and the task's retry
+     policy applies. Each payload was checked at enqueue, so a keyword in the payload schema does
+     not affect tasks already queued.
+- **Breaking: a contract `$ref` must be `#` or `#/$defs/<name>`, and `$anchor` is no longer
+  accepted** ([ADR 0039](../docs/decisions/0039-use-a-restricted-json-schema-contract-profile.md)).
+  `<name>` is a key of the root `$defs`. `ArgumentError` names any other reference with
+  `<path>.$ref must point at a subschema of the contract`, and also `$defs` below the root, a
+  `$defs` name that does not match `^[A-Za-z_][-A-Za-z0-9._]*$`, and `$anchor` at any depth. A
+  property named `$anchor` stays valid. Upgrade in this order:
+  1. Find each contract version that references anything other than `#` or a root definition, nests
+     `$defs`, uses `$anchor`, or names a definition outside that pattern.
+  2. Move each referenced or anchored subschema into the root `$defs` and reference it as
+     `#/$defs/<name>`. Rename each definition outside the pattern and update the references to it.
+     Declare a new contract version, because contract rows are immutable, and move `currentVersion`
+     to it.
+  3. Let tasks that hold the old version finish before you run Ruby workers. A removed form in a
+     task's result schema fails the attempt with `ArgumentError`, and the task's retry policy
+     applies.
+- Add the executor forms: a `PG::Connection`, a `ConnectionPool`, or any object whose `with`
+  yields a connection. `ActiveRecordExecutor` joins the caller's Active Record transaction.
+- Add the error hierarchy under `Stablemates::Workhorse::Error`.
+- Add the `Admin` operator client: task, timeline, checkpoint, progress, and wait inspection, dead
+  letter listing and redrive, worker pause, and queue pause, resume, and purge. Every control takes
+  an `AdminAudit`.
+- Add `Dashboard`, a Rack application that serves the operator dashboard under a Rails `mount` or a
+  `Rack::Builder#map`. It answers the dashboard/v1 procedures and serves the bundled browser app.
+- `Executor.for` ignores the `Object#with` that ActiveSupport defines, so a plain object is still
+  refused.
+- Add `Worker`: it claims, heartbeats, completes, fails, and retries tasks over a
+  `ConnectionPool`, and runs handlers on a thread pool of `concurrency` threads. A handler receives
+  its payload and a `HandlerContext` with the task and a `CancellationToken`. `stop` requests
+  shutdown. `run` then drains handlers within `shutdown_grace`, cancels the rest with `:shutdown`,
+  and raises `ShutdownIncompleteError` when any handler still runs.
+- Add the durable `HandlerContext` calls: `checkpoint`, `sleep`, `sleep_until`, `wait_for_signal`,
+  `wait_for_human`, `run_child`, `run_children`, `run_children_all`, `get_progress`, and
+  `set_progress`. A call that waits suspends the attempt and releases its lease, and the task
+  resumes in the same attempt. A handler that swallows the suspension still suspends, and the
+  worker logs `workhorse.handler.signal_swallowed`. After the lease is lost, every durable write
+  raises `LeaseLostError`; reads and checkpoint replays still return. A child without a queue runs on the worker's first queue.
+- Under Rails, handlers run inside `Rails.application.executor.wrap`. `run` warns when the Active
+  Record pool is smaller than `concurrency`.
+- `Worker` runs tasks on a fast-tier queue: it probes each queue with `complete_many_and_claim_v1`,
+  records one `fast_task_outcome` row per task, and fuses each completion with a refill claim.
+  `Worker.new(cohorts:)` splits the slots into dispatch cohorts; without it, the worker keeps one
+  below concurrency 8, else `concurrency / 8` from 2 through 8, capped by the pool's spare
+  connections. The handler thread pool now allows two threads per slot.
+  A fast-tier task's `HandlerContext` raises `FastTierUnsupportedError` for checkpoints,
+  progress writes, durable waits, and child tasks before any durable write. That holds for a
+  task claimed through `claim_many_v1` after its queue moved to the fast tier.
+- `HandlerContext#wait_for_signal`, `wait_for_human`, `run_child`, `run_children`, and
+  `run_children_all` validate each step name before the deferred tier read or any write, as
+  `checkpoint` and `sleep` do. An invalid name raises `ArgumentError`. A child set is checked for
+  its type and size before its names.
+- A pooled connection that PostgreSQL dropped is discarded through the pool's
+  `discard_current_connection`, so the next statement gets a fresh connection. Before, the pool
+  reused the dead connection until the process restarted. An ordinary SQL error keeps the
+  connection, and the failed statement is never resent.
+- `Worker` measures a result as PostgreSQL does, by the UTF-8 length of its `jsonb` text, before
+  it completes the task. A result over the task's limit fails only its own attempt with
+  `ValueSizeLimitError`, and the retry policy decides what happens next. The worker no longer stops
+  when PostgreSQL refuses an oversized completion. That holds on both tiers and for batch members.
+- Add `Worker#handle_batch` with `max_size:` and `linger:` in seconds. Once the worker stops, a
+  lingering batch runs as soon as every task it claimed has arrived.
+- Change the `handle_batch` block from `|payloads, context|` to `|items|`. Each `BatchHandlerItem`
+  holds a member's `payload` and its own `BatchHandlerContext` with `task`, `cancellation`,
+  `get_checkpoint`, `checkpoint`, `get_progress`, and `set_progress`. The batch-wide `tasks` and
+  shared `cancellation` are gone. Each write is fenced on its member's lease, and a member's
+  checkpoint replays whatever batch a retry puts it in. A fast-tier member's `checkpoint` and
+  `set_progress` raise `FastTierUnsupportedError` before any durable write.
+- Add `HandlerContext#get_checkpoint`.
+- `HandlerContext#checkpoint`, `sleep`, and `sleep_until` refuse a name outside 1 to 200
+  characters with `ArgumentError` before the block runs or any statement. `get_progress` keeps the
+  highest progress revision PostgreSQL acknowledged when `set_progress` calls return out of order.
+- The Active Job adapter's `enqueue_all` clears each job's `enqueue_error`, so a job reports only
+  the error of the current call.
+- Add `run_worker_process`, which stops the worker on `TERM` or `INT` and exits at once on a second
+  signal, and `run_worker_processes`, which forks, supervises, and restarts worker processes.
+- A `logger` that raises no longer reaches worker lifecycle code. An accepted heartbeat still
+  renews the lease, `Worker#stop` still wakes the dispatcher, and a second signal still exits the
+  process. The first failure of each logger is written to standard error.
+- Add the Active Job adapter, selected with `config.active_job.queue_adapter =
+:stablemates_workhorse`. It requires Active Job 8.0 or later. A default job runs under the
+  `active_job` task type. A typed job declares its task type with `workhorse_options` and carries
+  one JSON `Hash`, so another SDK can enqueue or run it. `Stablemates::Workhorse::ActiveJob.handle`
+  registers both formats on a `Worker`.
+- Workers built on one pool share one notification listener connection, as they share the
+  heartbeat connection. Each worker is woken only for its own queues, and the listener stops when
+  the last worker on the pool stops.
+- `EnqueueResult#reason` says why a debounced enqueue was `:non_replaceable`:
+  `:incompatible_key_mode`, `:not_pending`, or `:window_elapsed_pending`. It is `nil` for every other
+  outcome.

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but not
+      limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Stablemates
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/NOTICE

@@ -0,0 +1,6 @@
+Workhorse
+Copyright 2026 Stablemates
+
+This product includes software developed by Stablemates.
+The corresponding source is licensed under the Apache License, Version 2.0.
+See the LICENSE file in the repository root.

data/README.md

@@ -1 +1,104 @@
-Name reservation. Use stablemates-workhorse 0.6.0 or later.
+# Workhorse for Ruby
+
+The Ruby queue client, operator client, and worker runtime for the Workhorse durable task queue for
+PostgreSQL.
+
+> **Public beta:** Workhorse is usable for evaluation and early production adoption. A 0.x minor
+> release may change behaviour, so read the
+> [changelog](https://github.com/stablemates/workhorse/blob/main/ruby/CHANGELOG.md) before you
+> upgrade. It will not ask you to recreate your database: migrations are ordered, and inside a major
+> line a migration only adds, so a running deployment upgrades in place. The one exception is
+> migration 0025: a database from before 0.5.0 crosses it offline, with the
+> [0.5.0 upgrade steps](https://github.com/stablemates/workhorse/blob/main/CHANGELOG.md#050--2026-09-28).
+> The upgrade from 0.5 to 0.6 only adds.
+
+An AI agent should read [the Workhorse documentation index](https://workhorse.run/llms.txt) first.
+
+## Install
+
+Add the gem and the connection pool it runs on:
+
+```bash
+bundle add stablemates-workhorse
+bundle add connection_pool
+```
+
+Install the schema once, as a deployment step. The application never installs or migrates it.
+
+```bash
+npx --package @stablemates/workhorse@0.6.0 workhorse schema install
+```
+
+The machine that runs that deployment step needs Node.js 22 or newer. The application itself needs
+no Node.js.
+
+Pin that version to the gem version the application depends on. The two come from one commit of
+this repository, so the numbers match. A schema tool older than the application leaves a schema the
+application refuses to start against.
+
+Runtime processes verify compatibility instead of changing the schema. Call
+`Queue#assert_compatible` or `Admin#assert_compatible` at startup. A refusal is
+`Stablemates::Workhorse::CompatibilityError`, whose `code` names the reason.
+
+Requires Ruby 3.3 or newer and PostgreSQL 15 through 18.
+
+## Run one task
+
+```ruby
+require "connection_pool"
+require "pg"
+require "stablemates/workhorse"
+
+url = ENV.fetch("DATABASE_URL")
+pool = ConnectionPool.new(size: 4) { PG.connect(url) }
+
+queue = Stablemates::Workhorse::Queue.new(pool)
+enqueued = queue.enqueue("email.welcome", {"to" => "ada@example.com"})
+
+worker = Stablemates::Workhorse::Worker.new(pool)
+worker.handle("email.welcome") do |payload, _context|
+  {"deliveredTo" => payload["to"]}
+end
+worker.run_once # production uses Stablemates::Workhorse.run_worker_process(worker)
+
+task = Stablemates::Workhorse::Admin.new(pool).get_task(enqueued.task_id)
+puts "#{task.state} #{task.result}" if task
+```
+
+Handlers receive at-least-once delivery. Use stable provider idempotency keys around external
+effects. `ruby/examples/` also holds a transactional enqueue, a dedicated worker process, and an
+orchestration of child tasks, signals, and human decisions. An integration spec runs every one of
+them against PostgreSQL.
+
+## Package boundary
+
+The gem is `stablemates-workhorse`, and its namespace is `Stablemates::Workhorse`.
+
+- `Queue` enqueues, cancels, signals, and synchronizes schedules, policies, budgets, and contracts.
+  `Queue.new` accepts a `PG::Connection`, a `ConnectionPool`, or an open `pg` transaction.
+  `ActiveRecordExecutor` joins the caller's Active Record transaction instead. Either way, the
+  enqueue becomes part of your commit. When a statement finds its pooled connection unusable, the
+  SDK discards that connection through the pool's `discard_current_connection`. The SDK never
+  closes a connection the caller owns. A source without `discard_current_connection` must replace
+  an unusable connection itself.
+  Each enqueue returns an `EnqueueResult` with the task ID and an `outcome`. A debounced request
+  that was `:non_replaceable` also carries a `reason`: `:incompatible_key_mode`, `:not_pending`, or
+  `:window_elapsed_pending`.
+- `Worker` takes a pool, registers handlers by task type, and runs them under a lease with a shared
+  heartbeat connection. `run_worker_process` drains it on `TERM` or `INT`.
+- `HandlerContext` offers checkpoints, durable sleeps, signal and human waits, child tasks, and
+  progress. PostgreSQL owns every durable decision, and an unresolved wait suspends the task.
+- `Admin` lists, inspects, and repairs tasks, dead letters, waits, workers, and queues.
+- `Dashboard` is a Rack application that Rails routes or any Rack builder mounts under its own path.
+- The [Active Job adapter](https://workhorse.run/docs/active-job) runs Rails jobs on Workhorse.
+- When the application loads `opentelemetry-api`, the gem adds spans and trace propagation. Loading
+  `opentelemetry-metrics-api` as well adds metrics.
+
+The gem never installs or migrates the shared PostgreSQL schema.
+
+## Next
+
+- Follow the [quickstart](https://workhorse.run/docs/quickstart) and deploy
+  [worker processes](https://workhorse.run/docs/worker-processes).
+- Move Rails jobs over with the [Active Job adapter](https://workhorse.run/docs/active-job).
+- Read the [compatibility policy](https://workhorse.run/docs/compatibility).