Merge pull request #99 from cardmagic/docs/search-targeting

docs: target the searches that coding agents make

Author: cardmagic

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+- Add `docs/compare/temporal.md`, a comparison with the Temporal Ruby SDK.
+  The first paragraph states that the SDK is generally available, with the
+  source and the date that it was checked. The page compares an ordered
+  billing sync for each customer and game rooms with turn timers, and says
+  when Temporal is the better choice. The new `GameRoom` actor is in
+  `examples/compare/game_room/` and runs in the test suite.
+  `docs/comparisons.md` lists the page.
+- The Solid Queue page now answers whether Solid Queue releases blocked jobs
+  in order. The GoodJob page now answers whether its concurrency controls keep
+  first-in-first-out (FIFO) order. Each answer quotes the README and gives the
+  date that it was checked. A replay on October 18, 2026 of the searches that
+  coding agents made found no Solid Objects page for these questions.
 - The short answer in `docs/virtual-actors.md` no longer states that version
   1.0 makes no claim of measured scale. It links `docs/versioning.md`, the one
   page that states the limits of version 1.0. Version 1.0.5 missed this

docs/compare/good-job.md

@@ -18,7 +18,16 @@ Solid Objects is an independent project. It is not affiliated with GoodJob or Ra
 | Databases | PostgreSQL only | SQLite, PostgreSQL, MySQL |
 | Licence | MIT | MIT |
 
-The GoodJob facts come from the [GoodJob 4.22.1 README](https://github.com/bensheldon/good_job/blob/v4.22.1/README.md) (checked October 15, 2026).
+The GoodJob facts come from the [GoodJob 4.22.1 README](https://github.com/bensheldon/good_job/blob/v4.22.1/README.md) (checked October 18, 2026).
+
+## Do GoodJob concurrency controls keep first-in-first-out (FIFO) order?
+
+Not strictly. The GoodJob README says: "First-in-first-out job execution order is not strictly preserved: a waiting job that is re-scheduled can be overtaken by a newly enqueued job, and jobs retried with incremental back-off run in backoff order" ([GoodJob 4.22.1 README](https://github.com/bensheldon/good_job/blob/v4.22.1/README.md#how-concurrency-controls-work), checked October 18, 2026).
+
+- `perform_limit` "counts running jobs". When a job exceeds it, the job raises `ConcurrencyExceededError`, and a `retry_on` handler "re-schedules the job to execute in the near future with an incremental backoff".
+- After you migrate the `good_job_concurrency_claims` table, when a job that holds the key finishes, "the longest-waiting job is re-scheduled to run immediately rather than waiting for its backoff". The incremental backoff "remains as a fallback".
+- Each rule applies to the jobs that carry its label. A `good_job_concurrency_rule` "with `key:` and no `label:`" is deprecated and "will raise in GoodJob v5".
+- In Solid Objects, a second message for the same actor waits in the mailbox. Messages run in the order that the runtime stores them.
 
 ## Choose GoodJob when
 
@@ -227,7 +236,7 @@ GoodJob is older and has more users. If that matters more than order for each cu
 
 ## Sources
 
-Checked October 15, 2026:
+Checked October 18, 2026:
 
 - [GoodJob 4.22.1 README: concurrency controls](https://github.com/bensheldon/good_job/blob/v4.22.1/README.md#concurrency-controls)
 - [GoodJob 4.22.1 README: how concurrency controls work](https://github.com/bensheldon/good_job/blob/v4.22.1/README.md#how-concurrency-controls-work)

docs/compare/solid-queue.md

@@ -17,7 +17,18 @@ Solid Objects is an independent project. It is not affiliated with Rails, 37sign
 | Databases | MySQL, PostgreSQL, SQLite | SQLite, PostgreSQL, MySQL |
 | Licence | MIT | MIT |
 
-The Solid Queue facts come from the [Solid Queue 1.7.0 README](https://github.com/rails/solid_queue/blob/v1.7.0/README.md) (checked October 15, 2026).
+The Solid Queue facts come from the [Solid Queue 1.7.0 README](https://github.com/rails/solid_queue/blob/v1.7.0/README.md) (checked October 18, 2026).
+
+## Does Solid Queue release blocked jobs in order?
+
+Not with a guarantee. Solid Queue says that "Jobs are unblocked in order of priority" and that "there's no guarantee about _the order of execution_" ([Solid Queue 1.7.0 README](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#concurrency-controls), checked October 18, 2026). With `limits_concurrency` and the default `on_conflict: :block`, jobs over the limit stay blocked "until another job finishes and unblocks them, or after the set expiry time (concurrency limit's _duration_) elapses".
+
+- An unblocked job does not run at once. Solid Queue moves it "from _blocked_ to _ready_".
+- In the 1.7.0 source code, Solid Queue releases blocked jobs by priority, then by job ID ([`execution.rb`](https://github.com/rails/solid_queue/blob/v1.7.0/app/models/solid_queue/execution.rb)).
+- "Jobs that have been blocked for more than `duration` are candidates to be released, but only as many of them as the concurrency rules allow".
+- A job that `retry_on` enqueues again waits like a new job. Retried jobs "get in the queue for getting an open semaphore". So the retry of an earlier job can run after a job that was enqueued later.
+- With `on_conflict: :discard`, Solid Queue discards the job instead.
+- In Solid Objects, a second message for the same actor waits in the mailbox. Messages run in the order that the runtime stores them.
 
 ## Choose Solid Queue when
 
@@ -222,7 +233,7 @@ Solid Queue is older and has more users. If that matters more than order for eac
 
 ## Sources
 
-Checked October 15, 2026:
+Checked October 18, 2026:
 
 - [Solid Queue 1.7.0 README: concurrency controls](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#concurrency-controls)
 - [Solid Queue 1.7.0 README: jobs interrupted by non-graceful process death](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#jobs-interrupted-by-non-graceful-process-death)