fix: enforce deadlines and record ledger entries

Review found three gaps in the guide examples, and Rails 7.1 and 7.2
found two in the tests.

- EventTickets and SeatInventory now store each deadline and check it in
  the operation, so a hold past its deadline cannot be confirmed or
  extended and frees its seats even when the expiry reminder has not
  run. The reminder only cleans up. New tests travel past the deadline
  without delivering a reminder; both failed before the change.
- SeatInventory rejects a seat count that is not a positive integer. A
  hold for -5 seats had added five seats to the show.
- LedgerAccount kept the last 100 entry IDs in state, so a repeated
  entry after 100 newer entries changed the balance again. Each entry
  now writes a ledger_entries row through a commit action in the same
  transaction, with a unique index, and apply checks that row first. A
  test applies 102 entries and repeats the first; it failed before.
- On Rails 7.1 and 7.2, ActiveJob::TestHelper ignores a queue adapter
  assigned inside the test, so the lost-job test raised nothing. It now
  replaces perform_later for that test.
- On Rails 7.1 SQLite, two workers that registered their processes at
  the same time raised "database is locked". The test now creates both
  workers before the threads start.
- The Sidekiq snippet no longer carries the commented-out weighted
  line.

Codex with GPT-6 Astra revised the three affected guides from change
lists, and the guides embed the new example files.

Author: cardmagic

docs/guides/expiring-reservations.md

@@ -46,7 +46,8 @@ class SeatInventory < SolidObjects::Actor
   end
 
   def hold(hold_id:, buyer:, seats:)
-    return hold_result(hold_id) if holds.key?(hold_id)
+    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
 
@@ -59,8 +60,9 @@ class SeatInventory < SolidObjects::Actor
   end
 
   def extend_hold(hold_id:)
-    hold = holds[hold_id]
-    reject(:no_hold, "The hold expired or does not exist") unless hold
+    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
@@ -73,10 +75,9 @@ class SeatInventory < SolidObjects::Actor
 
   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[hold_id]
-    reject(:no_hold, "The hold expired or does not exist") unless hold
-
+    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)
@@ -92,8 +93,13 @@ class SeatInventory < SolidObjects::Actor
 
   private
 
+  def active_hold?(hold_id)
+    holds.key?(hold_id) && holds.dig(hold_id, "expires_at") > Time.current.to_i
+  end
+
   def seats_available
-    capacity - holds.values.sum { |hold| hold.fetch("seats") } - confirmed.values.sum
+    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)
@@ -103,19 +109,19 @@ 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`.
-- `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`.
-- `confirm` moves the hold to `confirmed` and cancels the reminder with `unschedule`. A confirmation retry returns the same result. After expiry, `confirm` rejects the request with the code `no_hold`.
-- `expire` releases the seats 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.
+- `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.
 
-All state stays bounded by the show capacity.
+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.
+`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.
 
@@ -130,6 +136,8 @@ Delivery is at least once, so `expire` checks the deadline before it changes any
 - 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).

docs/guides/ordered-jobs.md

@@ -65,11 +65,12 @@ Sidekiq.configure_server do |config|
   config.capsule("unsafe") do |cap|
     cap.concurrency = 1
     cap.queues = %w[queue_a queue_b] # strict priority
-    # cap.queues = %w[queue_a,3 queue_b,1] # weighted
   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.
@@ -113,21 +114,50 @@ This approach has two costs:
 There is one `LedgerAccount` actor for each account ID.
 
 ```ruby
-class LedgerAccount < SolidObjects::Actor
-  RECENT_ENTRY_LIMIT = 100
+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 :recent_entry_ids, default: -> { [] }
   attribute :statement_balance_cents, default: nil
 
   def apply(entry_id:, kind:, amount_cents:)
-    return balance_cents if recent_entry_ids.include?(entry_id)
+    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
-    self.recent_entry_ids = (recent_entry_ids + [ entry_id ]).last(RECENT_ENTRY_LIMIT)
+    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
@@ -138,6 +168,10 @@ class LedgerAccount < SolidObjects::Actor
 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
@@ -153,17 +187,18 @@ 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. A repeated delivery runs the method again. `apply` checks `recent_entry_ids` and returns without a change if the list contains the entry ID.
+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 balances are 25 and 0 cents.
+- 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
@@ -178,7 +213,7 @@ You do not assign sequence numbers. The actor mailbox gives the order.
 - 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 actor remembers the idempotency keys of its last finished turns. It retains 64 keys by default. See [retention and backups](../operations.md#retention-and-backups).
+- 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
 

docs/guides/race-conditions.md

@@ -109,18 +109,22 @@ class EventTickets < SolidObjects::Actor
   end
 
   def hold(buyer:, hold_id:)
+    release_expired_holds
     return { held: true, hold_id: } if holds.dig(buyer, "hold_id") == hold_id
     return { held: false, reason: "already_held" } if holds.key?(buyer)
     return { held: false, reason: "sold_out" } if seats_available.zero?
 
+    deadline = HOLD_DURATION.from_now
     self.seats_available -= 1
-    self.holds = holds.merge(buyer => { "hold_id" => hold_id })
-    schedule(at: HOLD_DURATION.from_now, key: buyer).expire(buyer:, hold_id:)
+    self.holds = holds.merge(buyer => { "hold_id" => hold_id, "expires_at" => deadline.to_i })
+    schedule(at: deadline, key: buyer).expire(buyer:, hold_id:)
     { held: true, hold_id: }
   end
 
   def confirm(buyer:, hold_id:)
     return { confirmed: true } if sold.include?(hold_id)
+
+    release_expired_holds
     reject(:no_hold, "The hold expired or does not exist") unless holds.dig(buyer, "hold_id") == hold_id
 
     self.holds = holds.except(buyer)
@@ -142,14 +146,24 @@ class EventTickets < SolidObjects::Actor
     self.title = title
     self.revision += 1
   end
+
+  private
+
+  def release_expired_holds
+    expired_buyers = holds.select { |_buyer, hold| hold.fetch("expires_at") <= Time.current.to_i }.keys
+    self.holds = holds.except(*expired_buyers)
+    self.seats_available += expired_buyers.length
+  end
 end
 ```
 
 The actor owns the lifecycle:
 
-- The `hold` method takes a seat and schedules a reminder with `schedule(at:, key: buyer)`. The database stores the reminder.
+- The `hold` method takes a seat and stores the deadline, `expires_at`, beside `hold_id` in the hold. It schedules a reminder with `schedule(at:, key: buyer)`. The database stores the reminder.
+- The `hold` and `confirm` methods first call the private `release_expired_holds` method. This method removes each hold at or past its deadline and returns its seat.
+- The stored deadline is the rule. After the deadline, the actor rejects confirmation, even before the reminder runs. A stopped or slow runtime process does not extend a hold.
 - The `confirm` method moves the hold to `sold` and cancels the reminder with `unschedule`.
-- The `expire` method releases the seat only when the `hold_id` still matches. An expiry for an old hold does nothing.
+- The `expire` method releases the seat only when the `hold_id` still matches. An expiry for an old hold does nothing. The reminder cleans up the hold if no other call releases it first.
 - A retry of `hold` with the same IDs returns the same result while that hold exists. A retry of `confirm` with the same IDs returns the same result after the confirmation. These retries make no further changes.
 - The `reject` method ends the call with a business result. The caller receives `SolidObjects::Rejected`. The runtime does not retry a rejection.
 
@@ -170,6 +184,7 @@ result = EventTickets.ref(event.id.to_s).hold(
 - **Stale expiry:** The first hold expires. The buyer holds again with a new hold ID. The old expiry arrives again, and the new hold stays.
 - **Retries:** Two identical holds and two identical confirmations sell one seat.
 - **Confirmation after expiry:** The actor rejects the confirmation with the code `no_hold`.
+- **Past the deadline, before the reminder runs:** The test moves the clock 11 minutes forward and delivers no reminder. The actor rejects the confirmation with `no_hold`, and another buyer holds the seat.
 - **Stale form:** The actor rejects the update with the code `stale_revision`. The next section explains this check.
 
 ## Serial execution does not stop a stale form

examples/guides/expiring_reservations/seat_inventory.rb

@@ -19,7 +19,8 @@ def open_show(capacity:)
   end
 
   def hold(hold_id:, buyer:, seats:)
-    return hold_result(hold_id) if holds.key?(hold_id)
+    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
 
@@ -32,8 +33,9 @@ def hold(hold_id:, buyer:, seats:)
   end
 
   def extend_hold(hold_id:)
-    hold = holds[hold_id]
-    reject(:no_hold, "The hold expired or does not exist") unless hold
+    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
@@ -46,10 +48,9 @@ def extend_hold(hold_id:)
 
   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[hold_id]
-    reject(:no_hold, "The hold expired or does not exist") unless hold
-
+    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)
@@ -65,8 +66,13 @@ def expire(hold_id:, expires_at:)
 
   private
 
+  def active_hold?(hold_id)
+    holds.key?(hold_id) && holds.dig(hold_id, "expires_at") > Time.current.to_i
+  end
+
   def seats_available
-    capacity - holds.values.sum { |hold| hold.fetch("seats") } - confirmed.values.sum
+    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)

examples/guides/ordered_jobs/create_ledger_entries.rb

@@ -0,0 +1,14 @@
+# rbs_inline: enabled
+
+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