solid_objects 0.17.1 → 0.17.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b918d2d78f5336b1eeda97b9f59560b6ef22cb4703524fd17c368c3fcb90b8d
-  data.tar.gz: 26483ce973457d40dceb52a14bb311417e476a9bd84ce8dc5f85e814a16db9af
+  metadata.gz: 218b1090ca466db8385017c23f98120d78b605b1db03a7ad69e82156c7669fe5
+  data.tar.gz: f0deae94f1fa479882d3d47bc5205c30d30b30c3aadfee663959ad7e787ff265
 SHA512:
-  metadata.gz: 0ac2d7b510bd69aad30b8b32c8330725c08e52625ceca66a0cfde34e61f316b904aa2f21705473034096560479ff94dbc8c8a072b68e0a4e852de89c182f2bcc
-  data.tar.gz: 7061098cc192a52606d2957380d8a6a6d842e8a67c2c13aad0873efcfdad691bb0783fbb5252554a896d5a2424a88d24cfb5454bdb80990c5b20a6b9c65f8847
+  metadata.gz: 97c597751ea4330ec9857faec8bc4ef8d3449891f29abd6d99fe13709e785971c42e6d3faf24ab02835685857104ad82e20df42088a0b84a32573a8519177368
+  data.tar.gz: db9450e6f7657b630cf6d6c2eb191a57614690ef7f34d3d47fea079a5bd388d1b7bc31b84ac22667b6cdd296f0a426e29f00acb20b3473fe53af0e656d146b28

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.17.3 - 2026-10-09
+
+- Add four problem guides in `docs/guides/`: preventing race conditions in
+  Rails, running jobs in order for each customer, expiring reservations, and
+  saving state and queuing work together. Each guide reproduces the failure,
+  shows the plain Rails fix first, and then shows a Solid Objects actor where
+  it adds value. The README and the agent guide list them.
+- Each guide embeds tested example files from `examples/guides/`. The tests in
+  `test/guides/` prove each claim: the race and its SQL fix, ordered entries
+  under two workers, a reminder that runs after a restart, a stale expiry that
+  changes nothing, an atomic actor turn, and an effect that runs twice with one
+  idempotency key. A document test fails when a guide does not embed the
+  current example files, contains an em dash or an en dash, or links to a
+  missing file.
+- Add `activejob` to the development and test bundle for the guide examples.
+  Compatibility runs pin it to the Rails line under test.
+
+## 0.17.2 - 2026-10-08
+
+- The README names the agent guide at the start of Installation, and the agent
+  guide says that a reminder changes state only when it runs under
+  `solid_objects start`, so a query must not compute expiry from the clock.
+- `docs/agents.md` now tells agents to install the current release instead of
+  a remembered version, says that step 5 is required before the first call,
+  shows the two arguments of `reject`, and lists four API mistakes from
+  agent-written code with the correct form. The gem description now states
+  the Ruby 3.3 and Rails 7.1 requirement, because agents in the discovery
+  evaluation claimed Rails 8.0.
+- Claim the Context7 library: `context7.json` now carries the library `url` and
+  the maintainer `public_key`.
+- Add the Context7 refresh workflow. A push to `main` that changes the README,
+  `context7.json`, `docs/`, or `examples/` asks Context7 to refresh the index.
+  It uses the `CONTEXT7_API_KEY` repository secret.
+
 ## 0.17.1 - 2026-10-08
 
 - Name the category in the gem metadata and the README: Solid Objects is a

data/README.md

@@ -39,12 +39,14 @@ And so much more.
 - [Good uses](#good-uses)
 - [When a transaction is better](#when-a-transaction-is-better)
 - [Guarantees and boundaries](#guarantees-and-boundaries)
+- [Guides](#guides)
 - [Read more](#read-more)
 - [Status and license](#status-and-license)
 
 ## Installation
 
-Solid Objects requires Ruby 3.3 or newer and Rails 7.1 or newer.
+Solid Objects requires Ruby 3.3 or newer and Rails 7.1 or newer. Coding agents
+should follow the [agent guide](docs/agents.md), which gives each step in order.
 
 ```bash
 bundle add solid_objects
@@ -163,6 +165,16 @@ SQL and should be allowed to enjoy that.
 Exactly once is not hiding in a more advanced configuration. Read the
 [correctness contract](docs/correctness.md) before using important data.
 
+## Guides
+
+Each guide starts from a problem, shows the plain Rails fix first, and tests
+every claim in [`test/guides/`](test/guides/):
+
+- [Prevent race conditions in Rails](docs/guides/race-conditions.md)
+- [Run jobs in order for each customer](docs/guides/ordered-jobs.md)
+- [Expiring reservations](docs/guides/expiring-reservations.md)
+- [Save state and queue work together](docs/guides/transactional-outbox.md)
+
 ## Read more
 
 - [Five-minute Rails guide](https://solidobjects.dev/5min/rails)

data/docs/agents.md

@@ -30,6 +30,13 @@ Select a simpler tool in these cases:
 The full checklist is in [Choosing Solid Objects](fit.md). The category guide
 is [Virtual actors in Ruby on Rails](virtual-actors.md).
 
+Problem guides compare the plain Rails fix with an actor and test each claim:
+
+- [Prevent race conditions in Rails](guides/race-conditions.md)
+- [Run jobs in order for each customer](guides/ordered-jobs.md)
+- [Expiring reservations](guides/expiring-reservations.md)
+- [Save state and queue work together](guides/transactional-outbox.md)
+
 ## 2. Package identity
 
 | Item | Value |
@@ -64,6 +71,12 @@ bin/rails solid_objects:doctor
 The generator adds an initializer and copies migrations into the application.
 The doctor checks the configuration, the tables, and one real actor round trip.
 
+Install the current release. `bundle add solid_objects` selects it. Do not pin
+a version that you remember from earlier work; the API changed between
+releases. The current version is on <https://rubygems.org/gems/solid_objects>.
+
+The generated policies deny every call. Do step 5 before you call an actor.
+
 The `json` gem 3.x works only with Active Support 8.1.4 or newer. On Rails
 7.1, 7.2, 8.0, or 8.1 before 8.1.4, pin `gem "json", "~> 2"` in the
 `Gemfile`. Without the pin, Active Support raises an `ArgumentError`, such as
@@ -153,11 +166,25 @@ Obey these rules in actor code:
 - Use `schedule(at:, key:)` for delayed work. A reminder is one named alarm
   for each actor and key. A new `schedule` with the same key moves the alarm.
 - Use `reject(code, message)` for a business rule failure that must not retry.
+  It takes a code and a message, for example
+  `reject(:room_full, "The room is full")`.
 - Do not write Active Record models directly in a handler. The runtime raises
   `SolidObjects::ApplicationWriteForbidden`. Use `commit_action` for a short
   write in the same database.
 - Do not call an external API in a handler. Use `emit` and an effect handler.
 - Write each handler so that it can run again. Delivery is at least once.
+- A reminder changes state only when it runs, and it runs only while
+  `solid_objects start` runs. Do not compute expiry from the clock in a query;
+  read the state that the reminder committed.
+
+Avoid these mistakes:
+
+| Mistake | Correct form |
+| --- | --- |
+| `schedule(at: deadline)` with no operation after it | `schedule(at: deadline, key: buyer).expire(buyer:)`. `schedule` stages a reminder only when you call an operation on its result |
+| `reject "room full"` | `reject(:room_full, "The room is full")` |
+| `id` inside an actor | `actor_id`. An actor has no `id` method |
+| `register_effect(:name) { \|context, arguments\| ... }` | `register_effect(:name) { \|arguments, context\| ... }`. The arguments come first |
 
 [Reminders](reminders.md) and the [architecture guide](architecture.md) give
 the full actor API.

data/docs/guides/expiring-reservations.md

@@ -0,0 +1,175 @@
+# Expiring reservations in Rails
+
+A reservation holds stock for a short time, until the buyer confirms it or the hold expires. The stock must never go below zero. A retry must not take stock twice. A late expiry must not cancel a newer state. Solid Objects (the gem solid_objects) puts the stock and its holds in one actor, with durable reminders for the deadlines.
+
+## Put the stock under the right identity
+
+An actor for each reservation cannot prevent an oversold show. Two reservations can take the same stock. Two reservation actors are two identities. They run at the same time, and neither actor sees the other actor's hold.
+
+Put the stock and all of its holds in the actor that owns the stock. This guide uses one actor for each show.
+
+## The plain SQL design
+
+- Store each hold in a table with its seats and an `expires_at` time.
+- Count free seats as the capacity minus confirmed seats minus holds whose `expires_at` is still in the future.
+- Insert a hold inside a transaction that locks the show row. Two holds cannot then both see the last seat.
+- This design needs no timer. An old hold no longer counts when its time passes.
+
+This design is not enough when an action must occur at the deadline. You need a timer for these actions:
+
+- Release a payment authorization.
+- Tell the buyer that the hold expired.
+- Update state that other code reads without the clock.
+- Start the next step of a workflow.
+
+The timer, a confirmation, and a client retry can all touch the same hold. Each path must take the same lock. Each path must handle a duplicate or late delivery.
+
+## The actor
+
+```ruby
+class SeatInventory < SolidObjects::Actor
+  HOLD_DURATION = 15.minutes
+  EXTENSION = 5.minutes
+  MAX_EXTENSIONS = 2
+
+  attribute :capacity, default: 0
+  attribute :holds, default: -> { {} }
+  attribute :confirmed, default: -> { {} }
+
+  query :seats_left do
+    seats_available
+  end
+
+  def open_show(capacity:)
+    self.capacity = capacity if self.capacity.zero?
+    seats_available
+  end
+
+  def hold(hold_id:, buyer:, seats:)
+    reject(:invalid_seats, "Hold at least one seat") unless seats.is_a?(Integer) && seats.positive?
+    return hold_result(hold_id) if active_hold?(hold_id)
+    return { status: "confirmed" } if confirmed.key?(hold_id)
+    reject(:not_enough_seats, "Only #{seats_available} seats are left") if seats > seats_available
+
+    deadline = HOLD_DURATION.from_now
+    self.holds = holds.merge(
+      hold_id => { "buyer" => buyer, "seats" => seats, "expires_at" => deadline.to_i, "extensions" => 0 }
+    )
+    schedule(at: deadline, key: hold_id).expire(hold_id:, expires_at: deadline.to_i)
+    hold_result(hold_id)
+  end
+
+  def extend_hold(hold_id:)
+    reject(:no_hold, "The hold expired or does not exist") unless active_hold?(hold_id)
+
+    hold = holds.fetch(hold_id)
+    reject(:extension_limit, "The hold cannot be extended again") if hold.fetch("extensions") >= MAX_EXTENSIONS
+
+    deadline = Time.at(hold.fetch("expires_at")) + EXTENSION
+    self.holds = holds.merge(
+      hold_id => hold.merge("expires_at" => deadline.to_i, "extensions" => hold.fetch("extensions") + 1)
+    )
+    schedule(at: deadline, key: hold_id).expire(hold_id:, expires_at: deadline.to_i)
+    hold_result(hold_id)
+  end
+
+  def confirm(hold_id:)
+    return { status: "confirmed" } if confirmed.key?(hold_id)
+    reject(:no_hold, "The hold expired or does not exist") unless active_hold?(hold_id)
+
+    hold = holds.fetch(hold_id)
+    self.holds = holds.except(hold_id)
+    self.confirmed = confirmed.merge(hold_id => hold.fetch("seats"))
+    unschedule(:expire, key: hold_id)
+    { status: "confirmed" }
+  end
+
+  def expire(hold_id:, expires_at:)
+    return seats_available unless holds.dig(hold_id, "expires_at") == expires_at
+
+    self.holds = holds.except(hold_id)
+    seats_available
+  end
+
+  private
+
+  def active_hold?(hold_id)
+    holds.key?(hold_id) && holds.dig(hold_id, "expires_at") > Time.current.to_i
+  end
+
+  def seats_available
+    held_seats = holds.each_key.select { |hold_id| active_hold?(hold_id) }.sum { |hold_id| holds.dig(hold_id, "seats") }
+    capacity - held_seats - confirmed.values.sum
+  end
+
+  def hold_result(hold_id)
+    { status: "held", expires_at: holds.dig(hold_id, "expires_at") }
+  end
+end
+```
+
+- `open_show` sets the capacity once.
+- `hold` takes seats and records a deadline 15 minutes from now. It schedules one reminder with the hold ID as its key. A retry with the same hold ID returns the same hold and takes no more seats. When too few seats remain, `hold` rejects the request with the code `not_enough_seats`. `hold` rejects a seat count that is not a positive integer with the code `invalid_seats`. Without this check, a hold for -5 seats adds seats to the show.
+- `extend_hold` adds 5 minutes, at most two times. It schedules the reminder again with the same key, which moves the alarm. It rejects a third extension with the code `extension_limit`. It accepts only an active hold: a hold whose stored deadline is still in the future. After the deadline, it rejects the request with the code `no_hold`, even before the expiry reminder runs. A stopped or slow runtime process does not extend a hold.
+- `confirm` moves the hold to `confirmed` and cancels the reminder with `unschedule`. A confirmation retry returns the same result. `confirm` accepts only an active hold whose stored deadline is still in the future. After the deadline, it rejects the request with the code `no_hold`, even before the expiry reminder runs.
+- The stored deadline is the rule. `expire` removes the old hold from the state only if the deadline in the message still matches the hold. After an extension, an expiry for the old deadline does nothing.
+- `seats_left` is a query. A query runs as an ordered read in the actor mailbox. `reference.snapshot` reads the committed state without a message row. A hold past its deadline no longer counts against the seats. `seats_left` and new holds see the seats again at the deadline.
+
+Active holds and confirmed seats are bounded by the show capacity. An expired hold stays in the state until its reminder runs.
+
+## Deadlines that survive a restart
+
+Use durable reminders for persistent timers in Rails.
+
+`schedule(at:, key:)` stores the reminder in the database in the same commit as the state change. A reminder is one named alarm for each actor and key. A new schedule with the same key moves the alarm. `unschedule(:expire, key: hold_id)` cancels it. The deadline check in `confirm` and `extend_hold` does not wait for the reminder.
+
+Reminders run only while `bundle exec solid_objects start` runs. A reminder that falls due while the process is stopped runs after the process starts again. A reminder runs an ordinary actor message, so it runs in order with the other calls for that show.
+
+Delivery is at least once, so `expire` checks the deadline before it changes anything. See [reminders](../reminders.md).
+
+## What the tests prove
+
+- Eight concurrent holds request one seat each against a capacity of five. Five succeed, and three receive the rejection code `not_enough_seats`.
+- A hold retry takes its seats once.
+- An extension moves the reminder to the new deadline. At 16 minutes, nothing runs. At 21 minutes, the expiry runs and the seats return.
+- An expiry for the old deadline changes nothing after an extension.
+- The actor rejects a third extension with the code `extension_limit`.
+- A confirmation retry returns the same result. The hold moves to `confirmed` once, and the confirmation cancels the reminder.
+- A confirmation after expiry receives the rejection code `no_hold`.
+- Past the deadline, before the reminder runs: the test moves the clock 16 minutes forward and delivers no reminder. The actor rejects the confirmation and the extension with `no_hold`, and both seats are free.
+- A hold for zero seats or for -5 seats is rejected with `invalid_seats`, and the free seats do not change.
+- A hold that falls due while the runtime is stopped expires after a restart.
+
+See [the tests for this guide](../../test/guides/expiring_reservations_test.rb).
+
+## Payment and other side effects
+
+Do not call a payment provider inside the actor. An effect can run more than once.
+
+- Stage the payment with `emit`.
+- Pass `context.id` to the provider as the idempotency key.
+- Confirm the hold in the actor after the payment succeeds.
+
+See [the transactional outbox guide](transactional-outbox.md).
+
+## Run it in production
+
+- Authorization: the generated policies deny every call. Write a policy. Pass `authorization_context:` on each call. See [authorization policies](../authorization.md).
+- Run `bundle exec solid_objects start` beside the web process.
+- Every actor call creates a durable message row. Solid Objects keeps terminal message history for 30 days by default. See [retention and backups](../operations.md#retention-and-backups).
+
+## Limits
+
+- Solid Objects requires Ruby 3.3 or newer and Rails 7.1 or newer.
+- Delivery is at least once. Each operation must be safe to run again.
+- There are no transactions across actors. A reservation that spans two shows needs its own design.
+- One busy show runs its calls one at a time. Many shows run at the same time.
+- The gem is pre-1.0 and makes no production-ready claim.
+
+## More information
+
+- [The example file](../../examples/guides/expiring_reservations/seat_inventory.rb)
+- [The tests for this guide](../../test/guides/expiring_reservations_test.rb)
+- [Prevent race conditions in Rails](race-conditions.md)
+- [Correctness and delivery semantics](../correctness.md)
+- [Virtual actors in Ruby on Rails](../virtual-actors.md)

data/docs/guides/ordered-jobs.md

@@ -0,0 +1,232 @@
+# Run jobs in order for each customer in Rails
+
+A Rails job queue does not keep one customer's job order when several workers run jobs or a job retries. You can serialize one queue, limit concurrency for each customer, or check a sequence number in the database. Solid Objects (the `solid_objects` gem) fits when each customer needs ordered commands, durable state, reminders, and recovery after a restart. Different customers still progress at the same time.
+
+## Reproduce the problem
+
+An account starts with a balance of 0 cents. The caller enqueues a deposit of 100 cents, then a withdrawal of 80 cents. If the withdrawal runs first, it fails because the balance is 0 cents.
+
+```ruby
+class Account < ApplicationRecord
+  class InsufficientFunds < StandardError; end
+  class OutOfSequence < StandardError; end
+
+  def apply_entry!(kind:, amount_cents:)
+    change = (kind == "deposit") ? amount_cents : -amount_cents
+    raise InsufficientFunds, "balance #{balance_cents}, change #{change}" if balance_cents + change < 0
+
+    update!(balance_cents: balance_cents + change)
+  end
+
+  def apply_entry_in_sequence!(sequence:, kind:, amount_cents:)
+    with_lock do
+      raise OutOfSequence, "expected #{next_sequence}, received #{sequence}" if sequence > next_sequence
+      next if sequence < next_sequence
+
+      apply_entry!(kind:, amount_cents:)
+      update!(next_sequence: next_sequence + 1)
+    end
+  end
+end
+```
+
+`apply_entry!` adds a deposit or subtracts a withdrawal, then updates the balance. It raises `Account::InsufficientFunds` if the result is below 0. The later section uses `apply_entry_in_sequence!` to fix the order.
+
+The plain job calls `apply_entry!`:
+
+```ruby
+class ApplyEntryUnorderedJob < ApplicationJob
+  def perform(account_id:, kind:, amount_cents:)
+    Account.find(account_id).apply_entry!(kind:, amount_cents:)
+  end
+end
+```
+
+Order breaks for these reasons:
+
+- Several workers take jobs from the queue at the same time.
+- A job that fails and retries runs after newer jobs.
+- A job that waits for a lock can finish after a later job.
+
+The test performs the withdrawal job before the deposit job. The withdrawal raises `Account::InsufficientFunds`. See [the ordered jobs tests](../../test/guides/ordered_jobs_test.rb).
+
+## Native options
+
+| Option | What it gives | What it costs |
+| --- | --- | --- |
+| One serial queue (a Sidekiq capsule with concurrency 1) | One job at a time for the queues of that capsule, in each Sidekiq process | Every customer in that queue waits for every other customer. Sidekiq sets concurrency for each process. One order across the deployment needs one process for that queue. |
+| Solid Queue `limits_concurrency` with the customer as the key | At most `to` jobs at a time for each key (`to` is 1 by default) | Solid Queue gives “no guarantee about the order of execution, only about jobs being performed at the same time”. |
+| A sequence number and a row lock | Order for each customer | The code that enqueues must assign the sequence numbers. An early job raises an exception and retries. A job that fails on each attempt holds back the later jobs. |
+
+Sidekiq supports capsules from Sidekiq 7.0. A capsule can provide serial execution for a queue. The wiki says, “Do not declare a capsule for each queue.” Concurrency applies to each process. By default, one Sidekiq process creates five threads ([checked October 9, 2026](https://github.com/sidekiq/sidekiq/wiki/Advanced-Options#capsules)).
+
+```ruby
+Sidekiq.configure_server do |config|
+  config.capsule("unsafe") do |cap|
+    cap.concurrency = 1
+    cap.queues = %w[queue_a queue_b] # strict priority
+  end
+end
+```
+
+This snippet comes from the Sidekiq wiki.
+
+Solid Queue accepts `key`, `to`, `duration`, and `on_conflict` for concurrency controls. It requires `key` and sets `to` to 1 by default. A blocked job stays blocked until another job finishes or the duration expires. These controls do not guarantee execution order. Solid Queue does not use queue order to unblock jobs ([checked October 9, 2026](https://github.com/rails/solid_queue#concurrency-controls)).
+
+If one serial queue is fast enough for your volume, it is the simplest choice. If order does not matter, `limits_concurrency` is enough for one job at a time per customer.
+
+## Keep order with a sequence number
+
+`apply_entry_in_sequence!` locks the account row and checks the sequence number:
+
+- If the entry arrives early, the method raises `Account::OutOfSequence`.
+- If the account already applied that sequence, the method skips the entry.
+- If the entry has the expected sequence, the method applies it and moves `next_sequence` forward.
+
+The job calls this method:
+
+```ruby
+class ApplyEntryJob < ApplicationJob
+  retry_on Account::OutOfSequence, wait: 5.seconds, attempts: 20
+
+  def perform(account_id:, sequence:, kind:, amount_cents:)
+    Account.find(account_id).apply_entry_in_sequence!(sequence:, kind:, amount_cents:)
+  end
+end
+```
+
+`retry_on` re-enqueues the job when its entry arrives early.
+
+The tests show these results:
+
+- Sequence 2 first raises `Account::OutOfSequence`.
+- Sequences 1 and 2 then apply in order.
+- A repeated sequence 1 causes no change.
+- The job enqueues a retry when its entry arrives early.
+
+This approach has two costs:
+
+- The caller allocates the sequence numbers.
+- A broken entry blocks the account until someone fixes it.
+
+## One actor for each account
+
+There is one `LedgerAccount` actor for each account ID.
+
+```ruby
+class CreateLedgerEntries < ActiveRecord::Migration[7.1]
+  def change
+    create_table :ledger_entries do |table|
+      table.string :account_id, null: false
+      table.string :entry_id, null: false
+      table.string :kind, null: false
+      table.integer :amount_cents, null: false
+      table.timestamps
+    end
+    add_index :ledger_entries, [ :account_id, :entry_id ], unique: true
+  end
+end
+```
+
+The migration creates a `ledger_entries` table with a unique index on the account ID and the entry ID. `LedgerEntry` is a plain Active Record model for this table.
+
+```ruby
+SolidObjects.register_commit_action(:record_ledger_entry) do |arguments, _context|
+  LedgerEntry.create!(
+    account_id: arguments.fetch("account_id"),
+    entry_id: arguments.fetch("entry_id"),
+    kind: arguments.fetch("kind"),
+    amount_cents: arguments.fetch("amount_cents")
+  )
+end
+```
+
+The initializer registers the commit action `record_ledger_entry`. A commit action writes application rows inside the actor transaction. The entry row and the new balance commit together or not at all. A commit action needs Solid Objects and `ActiveRecord::Base` to share one connection pool.
+
+Commit actions can run again after a database rollback. Keep them deterministic, bounded, and database-only. Actor handlers can read application records. They cannot write them directly.
+
+```ruby
+class LedgerAccount < SolidObjects::Actor
+  attribute :balance_cents, default: 0
+  attribute :statement_balance_cents, default: nil
+
+  def apply(entry_id:, kind:, amount_cents:)
+    return balance_cents if LedgerEntry.exists?(account_id: actor_id, entry_id:)
+
+    change = (kind == "deposit") ? amount_cents : -amount_cents
+    reject(:insufficient_funds, "The balance is too low for this withdrawal") if balance_cents + change < 0
+
+    self.balance_cents += change
+    commit_action(:record_ledger_entry, account_id: actor_id, entry_id:, kind:, amount_cents:)
+    schedule(at: 1.day.from_now, key: "daily").close_statement
+    balance_cents
+  end
+
+  def close_statement
+    self.statement_balance_cents = balance_cents
+  end
+end
+```
+
+`apply` first checks `LedgerEntry.exists?` for the account and the entry. If the row exists, `apply` returns the balance and changes nothing. Calls for one account run one at a time, so this check and the insert cannot race.
+
+The unique index provides another check. A duplicate insert fails the turn. The actor does not apply the entry twice.
+
+The caller sends each entry with `async` and an idempotency key:
+
+```ruby
+LedgerAccount.ref(account.id.to_s)
+  .async(idempotency_key: entry.id.to_s, authorization_context: Current.user)
+  .apply(entry_id: entry.id.to_s, kind: entry.kind, amount_cents: entry.amount_cents)
+```
+
+The runtime stores the message in SQL before `async` returns. Messages for one actor run one at a time, in the order the runtime receives them. Different accounts run at the same time on different workers.
+
+The actor treats a business rejection and an exception differently:
+
+- `reject` ends an entry with a business result, such as `insufficient_funds`. The runtime does not retry the rejection. The next entry runs.
+- An exception causes the runtime to retry that message. The message holds back later messages for that account until it succeeds or moves to dead letters.
+
+A repeated enqueue with the same idempotency key creates one message while the first message row exists. A repeated delivery runs the method again. In both cases, the `ledger_entries` row stops a second change. This record does not expire.
+
+`schedule(at: 1.day.from_now, key: "daily")` keeps one statement reminder for each account. Each new entry moves the reminder. The database stores the reminder, and the reminder runs after a restart.
+
+You do not assign sequence numbers. The actor mailbox gives the order.
+
+## What the tests prove
+
+- The tests enqueue five entries for two accounts in one mixed order. Two workers process them. Each account applies its own entries in enqueue order. The tests read the order from the `ledger_entries` rows of each account. The balances are 25 and 0 cents.
+- The actor rejects a withdrawal that is too large. The deposit after it applies.
+- Two enqueues share the same idempotency key. One more direct delivery repeats the entry. The account applies the entry once.
+- The account applies 102 entries. Then the first entry arrives again. The balance does not change.
+- The statement reminder runs after the test resets the caller process.
+
+## Choose
+
+- Independent jobs: use a normal queue.
+- One job at a time for each customer, order not important: use `limits_concurrency`.
+- Low volume and one order for everything: use one serial queue.
+- Order for each customer plus durable state, reminders, and recovery: use an actor for each customer.
+
+## Run it in production
+
+- Run `bundle exec solid_objects start`. Async messages and reminders run only while this process runs. The database keeps unfinished work in SQL while the process does not run.
+- The generated policies deny every call. Write a policy. Pass `authorization_context:` to `async`. See [authorization policies](../authorization.md).
+- A message that fails on every attempt moves to dead letters after five attempts by default. Later messages then run. An operator can retry a dead letter. See [dead letters, retry, and redrive](../operations.md#dead-letters-retry-and-redrive).
+- The runtime remembers the idempotency keys of the last 64 finished turns for each actor. That window is not enough for money. The `ledger_entries` table is the durable record. See [retention and backups](../operations.md#retention-and-backups).
+
+## Limits
+
+- Solid Objects requires Ruby 3.3 or newer and Rails 7.1 or newer.
+- Delivery is at least once. Each operation must be safe to run again.
+- The gem provides no transactions across actors. A transfer between two accounts needs its own design, for example one SQL transaction on normal tables.
+- One busy account runs its entries one at a time.
+- The gem is pre-1.0 and makes no production-ready claim.
+
+## More information
+
+- [The example files](../../examples/guides/ordered_jobs/ledger_account.rb)
+- [The tests for this guide](../../test/guides/ordered_jobs_test.rb)
+- [Correctness and delivery semantics](../correctness.md)
+- [Reminders](../reminders.md)
+- [Prevent race conditions in Rails](race-conditions.md)