solid_objects 0.17.1 → 0.17.3

data/docs/guides/race-conditions.md

@@ -0,0 +1,236 @@
+# Prevent race conditions in Rails
+
+Most Rails races need a database constraint, an atomic update, a row lock, or optimistic locking. A virtual actor helps when one resource has a lifecycle. Requests, jobs, and timers change it, and these changes must occur in order and survive a restart. Solid Objects (the `solid_objects` gem) provides that actor on the SQL database that the application already uses.
+
+## Choose the right tool
+
+| Problem | Start with | When Solid Objects becomes relevant |
+| --- | --- | --- |
+| Duplicate records | A unique index in the database | A larger entity lifecycle also needs ordered durable work |
+| Concurrent increments or an inventory decrement | An atomic SQL update or a short transaction | The operation is part of holds, expiry, retries, and later commands |
+| Two people edit from an old form | Optimistic locking or a revision check | The entity also needs coordination across jobs and requests |
+| Several database changes in one request | A transaction and the correct row locks | Work must continue after that transaction and survive failures |
+| Commands that arrive through requests, jobs, and reminders | An explicit coordination design | This is the main use for an actor. The rest of this guide shows it |
+
+## Use the Rails tools first
+
+### Unique index
+
+A Rails uniqueness validation does not create a uniqueness constraint in the database. Two database connections can create two records with the same value. The validation alone does not stop duplicates.
+
+Create a unique index on the column in the database. See the [Rails Guides, section 2.10: uniqueness](https://guides.rubyonrails.org/active_record_validations.html) (checked October 9, 2026).
+
+### Pessimistic locking
+
+Rails supports row-level locks through `SELECT … FOR UPDATE`. The `with_lock` method wraps the block in a transaction. It reloads the object with a lock before it runs the block.
+
+```ruby
+event.with_lock do
+  event.update!(seats_available: event.seats_available - 1) if event.seats_available.positive?
+end
+```
+
+See the [Rails pessimistic locking reference](https://api.rubyonrails.org/classes/ActiveRecord/Locking/Pessimistic.html) (checked October 9, 2026).
+
+### Optimistic locking
+
+Active Record uses an integer `lock_version` column for optimistic locking. Each update increments `lock_version`. A stale save raises `ActiveRecord::StaleObjectError`.
+
+The Rails documentation recommends a hidden `lock_version` field in the form. That field lets the check work across web requests. See the [Rails optimistic locking reference](https://api.rubyonrails.org/classes/ActiveRecord/Locking/Optimistic.html) (checked October 9, 2026).
+
+## A worked example: ticket holds
+
+An event has a fixed number of seats. Buyers hold seats before they pay.
+
+### Step 1: Reproduce the race
+
+Two requests load the same event. Each request sees one free seat. Each request writes the value it computed. Both holds succeed, although the event has only one seat.
+
+```ruby
+class Event < ApplicationRecord
+  def hold_seat_unsafely
+    return false if seats_available.zero?
+
+    update!(seats_available: seats_available - 1)
+    true
+  end
+
+  def hold_seat
+    self.class.where(id:).where("seats_available > 0")
+      .update_all("seats_available = seats_available - 1") == 1
+  end
+end
+```
+
+The `hold_seat_unsafely` method shows the race. The `hold_seat` method provides the fix in step 2.
+
+The test reproduces the race without timed delays. It loads two copies of the event, then holds a seat with each copy. Both holds succeed. See [the race condition tests](../../test/guides/race_conditions_test.rb).
+
+### Step 2: Fix it with one SQL statement
+
+The `hold_seat` method lets the database decide. The `UPDATE` changes the row only when a seat is free. The method returns `true` only when the statement changes one row.
+
+In the test, ten requests load the event before they wait at a barrier. Then they try to hold seats at the same time. The event has three seats. Exactly three holds succeed.
+
+Stop here if a hold never expires and no later operation changes it. An atomic SQL update is the correct fix for a simple counter.
+
+### Step 3: The lifecycle needs more than a lock
+
+A real ticket hold has more requirements:
+
+- A hold expires after 10 minutes if the buyer does not pay.
+- The buyer confirms the hold after payment.
+- A client retries a hold or a confirmation after a timeout.
+- The process restarts before the holds expire.
+- An expiry that arrives late must not release a newer hold.
+
+A pure SQL design needs a holds table, an expiry job, retry keys, and recovery after a restart. Every path must take the same lock in the same order.
+
+### Step 4: One actor owns the event
+
+There is one `EventTickets` actor for each event ID. Calls for one actor run one at a time, in order. Different events can run at the same time.
+
+```ruby
+class EventTickets < SolidObjects::Actor
+  HOLD_DURATION = 10.minutes
+
+  attribute :opened, default: false
+  attribute :seats_available, default: 0
+  attribute :holds, default: -> { {} }
+  attribute :sold, default: -> { [] }
+  attribute :title, default: ""
+  attribute :revision, default: 0
+
+  def open_sales(seats:)
+    return seats_available if opened
+
+    self.opened = true
+    self.seats_available = seats
+  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, "expires_at" => deadline.to_i })
+    schedule(at: deadline, key: buyer).expire(buyer:, hold_id:, expires_at: deadline.to_i)
+    { 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)
+    self.sold = sold + [ hold_id ]
+    unschedule(:expire, key: buyer)
+    { confirmed: true }
+  end
+
+  def expire(buyer:, hold_id:, expires_at:)
+    return seats_available unless holds[buyer] == { "hold_id" => hold_id, "expires_at" => expires_at }
+
+    self.holds = holds.except(buyer)
+    self.seats_available += 1
+  end
+
+  def update_details(title:, base_revision:)
+    reject(:stale_revision, "Reload the event and try again") unless base_revision == revision
+
+    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 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 reminder passes the stored deadline: `expire(buyer:, hold_id:, expires_at:)`. The `expire` method releases the seat only when both the hold ID and the deadline still match the stored hold. An expiry for an old hold does nothing. An expiry that the scheduler queued before a retry created a fresh hold with the same hold ID also 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.
+
+Call the actor from a controller:
+
+```ruby
+result = EventTickets.ref(event.id.to_s).hold(
+  buyer: Current.user.id.to_s,
+  hold_id: params.require(:hold_id),
+  authorization_context: Current.user
+)
+```
+
+### Step 5: What the tests prove
+
+- **Concurrent holds:** Ten concurrent hold calls against three seats produce exactly three successful holds.
+- **Restart before expiry:** The test resets the caller process. It runs due reminders at 9 minutes and at 11 minutes. Nothing runs at 9 minutes. The expiry runs at 11 minutes, and the seat returns.
+- **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.
+- **A retry with the same hold ID after the deadline:** the test moves the clock 11 minutes forward. The retry creates a fresh hold, and then the old expiry arrives. The fresh hold stays.
+- **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
+
+An actor runs one call at a time. A stale form can still replace newer data. If two people load revision 0 and both submit, the second submit still runs after the first.
+
+Use a domain operation or a revision check. The example's `update_details` method rejects a call when `base_revision` differs from the current revision.
+
+## Run it in production
+
+### Authorization
+
+The install generator creates policies that deny every call. Write a policy that checks the caller and the actor type. For example, the policy can check a signed-in user.
+
+Pass `authorization_context:` on each call. An actor ID is not a permission. See [authorization policies](../authorization.md).
+
+### The runtime process
+
+Reminders run only while `bundle exec solid_objects start` runs. SQL keeps the unfinished work while the runtime process is down. The runtime process runs an overdue reminder after it starts again. See [reminders](../reminders.md).
+
+### Retention cost
+
+Every actor call creates a durable message row. The default `message_retention` keeps terminal message history for 30 days. Actor state stays until you destroy the actor or configure `instance_retention_by_actor_type`.
+
+In this example, the event capacity bounds the state. See [retention and backups](../operations.md#retention-and-backups).
+
+### External effects
+
+Do not call a payment provider inside the actor. Use `emit` and an effect handler. Pass `context.id` to the provider as the idempotency key.
+
+Delivery is at least once, so an effect can run more than once. See [effect idempotency](../agents.md#8-make-external-effects-idempotent).
+
+## Limits
+
+- Solid Objects requires Ruby 3.3 or newer and Rails 7.1 or newer.
+- Delivery is at least once, not exactly once. Write each operation so that it can run again.
+- There are no transactions across actors. A change that must touch two events atomically needs one SQL transaction on normal tables.
+- One busy event runs its calls one at a time. Many events can run at the same time.
+- The gem is pre-1.0 and makes no production-ready claim.
+
+## More information
+
+- [The example files](../../examples/guides/race_conditions/event_tickets.rb)
+- [The tests for this guide](../../test/guides/race_conditions_test.rb)
+- [Correctness and delivery semantics](../correctness.md)
+- [Virtual actors in Ruby on Rails](../virtual-actors.md)
+- [Expiring reservations](expiring-reservations.md)
+- [Ordered jobs for each customer](ordered-jobs.md)

data/docs/guides/transactional-outbox.md

@@ -0,0 +1,156 @@
+# Save state and queue work together in Rails
+
+A database commit and a job enqueue are two separate steps. If the process stops between them, the database keeps the data, but the queue receives no work. The transactional outbox pattern writes the work into the same database transaction as the data. A separate process delivers the work later. A Solid Objects actor, from the `solid_objects` gem, commits its state, its database writes, and its staged effects in one transaction.
+
+## Reproduce the lost job
+
+```ruby
+class Order < ApplicationRecord
+  def self.place_and_enqueue!(reference:, total_cents:)
+    order = create!(reference:, total_cents:)
+    ShipmentJob.perform_later(order_id: order.id)
+    order
+  end
+
+  def self.place_with_outbox!(reference:, total_cents:)
+    transaction do
+      order = create!(reference:, total_cents:)
+      OutboxMessage.create!(name: "request_shipment", arguments: { "order_id" => order.id })
+      order
+    end
+  end
+end
+```
+
+```ruby
+class ShipmentJob < ApplicationJob
+  def perform(order_id:)
+    order = Order.find(order_id)
+    ShippingProvider.create_shipment(idempotency_key: "order-#{order.id}", order_reference: order.reference)
+  end
+end
+```
+
+In `place_and_enqueue!`, `create!` commits the order. Then `perform_later` sends the job to the queue. The test uses a queue adapter that stops the process before the job reaches the queue. The order exists, but no job exists.
+
+`after_commit` and `enqueue_after_transaction_commit` have the same gap: they enqueue the job after the database commit.
+
+The Rails Guides state that `enqueue_after_transaction_commit` defers the enqueue until the Active Record transaction commits successfully. If the transaction rolls back, Rails does not enqueue the job. Rails 8 configures Solid Queue on a separate database by default. With this default, the job row and the order row use two databases. See [the Rails Guides, section 6.6.1](https://guides.rubyonrails.org/active_job_basics.html) (checked October 9, 2026).
+
+[The transactional outbox tests](../../test/guides/transactional_outbox_test.rb) demonstrate the crash gap.
+
+## The plain outbox pattern
+
+In `place_with_outbox!`, the model writes the order and an outbox row in one transaction.
+
+```ruby
+class OutboxMessage < ApplicationRecord
+  JOBS = { "request_shipment" => ShipmentJob }.freeze
+
+  scope :pending, -> { where(delivered_at: nil).order(:id) }
+
+  def self.relay(limit: 100)
+    pending.limit(limit).each do |message|
+      JOBS.fetch(message.name).perform_later(**message.arguments.symbolize_keys)
+      message.update!(delivered_at: Time.current)
+    end
+  end
+end
+```
+
+The `relay` method uses these steps:
+
+1. It sends each undelivered row to the queue.
+2. It marks the row as delivered.
+
+If the process stops after the enqueue and before the mark, the next relay sends the row again. The job must be idempotent. `ShipmentJob` passes `order-<id>` to the provider as the idempotency key.
+
+Rails Event Store uses this pattern. Its scheduler writes the job into the same database table within the same transaction. A separate `res_outbox` process sends those rows to the background jobs tool. See [Rails Event Store](https://railseventstore.org/docs/advanced-topics/outbox) (checked October 9, 2026).
+
+The plain outbox pattern is a good choice for an application that does not use actors.
+
+## The atomic boundary of an actor turn
+
+```ruby
+class Checkout < SolidObjects::Actor
+  attribute :status, default: "open"
+  attribute :total_cents, default: 0
+  attribute :shipment_id, default: nil
+
+  def place(total_cents:)
+    return status unless status == "open"
+
+    self.status = "placed"
+    self.total_cents = total_cents
+    commit_action(:record_order, reference: actor_id, total_cents:)
+    emit(:request_shipment, order_reference: actor_id, on_success: :shipment_requested)
+    status
+  end
+
+  def shipment_requested(effect_id:, arguments:, result:)
+    self.status = "shipping"
+    self.shipment_id = result.fetch("shipment_id")
+  end
+end
+```
+
+```ruby
+SolidObjects.register_commit_action(:record_order) do |arguments, _context|
+  Order.create!(reference: arguments.fetch("reference"), total_cents: arguments.fetch("total_cents"))
+end
+
+SolidObjects.register_effect(:request_shipment) do |arguments, context|
+  ShippingProvider.create_shipment(
+    idempotency_key: context.id,
+    order_reference: arguments.fetch("order_reference")
+  )
+end
+```
+
+One successful turn commits the actor state, the staged effects, the same-database commit actions, the reminders, and the outbound messages together. Actor Ruby code and external I/O run outside the actor-state transaction.
+
+- `commit_action(:record_order, ...)` writes the `orders` row inside that transaction. A commit action requires Solid Objects and `ActiveRecord::Base` to share one connection pool. It can run again after a database rollback. Keep each commit action deterministic, bounded, and database-only.
+- `emit(:request_shipment, ...)` stages an effect row in the same transaction. After the commit, an effect worker calls the handler outside any database transaction.
+- The handler passes `context.id` to the provider as the idempotency key. `context.id` is the effect ID. It stays the same on every attempt.
+- `on_success: :shipment_requested` sends the provider result back to the actor as a normal message.
+- If the turn raises, it commits no state, no order row, and no effect row.
+- `place` returns early when the checkout is not open. A repeated call stages no additional order or effect.
+
+## What Solid Objects does not do
+
+- Solid Objects does not wrap ordinary Active Record writes. Code outside an actor keeps its own transactions.
+- A direct Active Record write inside an actor operation raises `SolidObjects::ApplicationWriteForbidden`. A registered commit action provides the only path for application row writes inside the actor commit.
+- A commit action is unavailable when Solid Objects uses a separate database. Use `emit` with an idempotent effect consumer. Two databases cannot share one transaction.
+- Solid Objects does not provide exactly-once delivery. An effect can run more than once.
+
+## What the tests prove
+
+- A stop before the enqueue saves the order and loses the job.
+- A failure between the order insert and the outbox insert saves neither row.
+- The relay sends a message twice after a lost mark, and the provider creates one shipment.
+- A failed turn keeps no state, no order row, and no effect row.
+- A successful turn stores the state, the order row, and the effect row together.
+- Repeated `place` calls stage one order and one effect in total.
+- The provider response fails to reach the effect worker once. The effect runs again with the same `context.id`. The provider creates one shipment, and the actor records the shipment ID.
+
+## Run it in production
+
+- Run `bundle exec solid_objects start`. Effects and their callbacks run only while this process runs. The SQL database keeps undelivered effects while the process does not run.
+- Register effects and commit actions in an initializer at boot.
+- The generated policies deny every call. Write a policy. Pass `authorization_context:` on each call. See [authorization policies](../authorization.md).
+- See [effect recovery](../effect-recovery.md) for effects whose worker stopped during a call.
+
+## Limits
+
+- Solid Objects requires Ruby 3.3 or newer and Rails 7.1 or newer.
+- Delivery is at least once. Each effect handler must deduplicate with `context.id`.
+- Solid Objects provides no transactions across actors.
+- The gem is pre-1.0 and makes no production-ready claim.
+
+## More information
+
+- [The example files](../../examples/guides/transactional_outbox/checkout.rb)
+- [The tests for this guide](../../test/guides/transactional_outbox_test.rb)
+- [Correctness and delivery semantics](../correctness.md)
+- [Expiring reservations](expiring-reservations.md)
+- [Prevent race conditions in Rails](race-conditions.md)

data/examples/guides/expiring_reservations/seat_inventory.rb

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

data/examples/guides/ordered_jobs/account.rb

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

data/examples/guides/ordered_jobs/apply_entry_job.rb

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

data/examples/guides/ordered_jobs/apply_entry_unordered_job.rb

@@ -0,0 +1,7 @@
+# rbs_inline: enabled
+
+class ApplyEntryUnorderedJob < ApplicationJob
+  def perform(account_id:, kind:, amount_cents:)
+    Account.find(account_id).apply_entry!(kind:, amount_cents:)
+  end
+end

data/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

data/examples/guides/ordered_jobs/ledger_account.rb

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

data/examples/guides/ordered_jobs/ledger_entry.rb

@@ -0,0 +1,4 @@
+# rbs_inline: enabled
+
+class LedgerEntry < ApplicationRecord
+end

data/examples/guides/ordered_jobs/solid_objects.rb

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

data/examples/guides/race_conditions/event.rb

@@ -0,0 +1,15 @@
+# rbs_inline: enabled
+
+class Event < ApplicationRecord
+  def hold_seat_unsafely
+    return false if seats_available.zero?
+
+    update!(seats_available: seats_available - 1)
+    true
+  end
+
+  def hold_seat
+    self.class.where(id:).where("seats_available > 0")
+      .update_all("seats_available = seats_available - 1") == 1
+  end
+end

data/examples/guides/race_conditions/event_tickets.rb

@@ -0,0 +1,66 @@
+# rbs_inline: enabled
+
+class EventTickets < SolidObjects::Actor
+  HOLD_DURATION = 10.minutes
+
+  attribute :opened, default: false
+  attribute :seats_available, default: 0
+  attribute :holds, default: -> { {} }
+  attribute :sold, default: -> { [] }
+  attribute :title, default: ""
+  attribute :revision, default: 0
+
+  def open_sales(seats:)
+    return seats_available if opened
+
+    self.opened = true
+    self.seats_available = seats
+  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, "expires_at" => deadline.to_i })
+    schedule(at: deadline, key: buyer).expire(buyer:, hold_id:, expires_at: deadline.to_i)
+    { 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)
+    self.sold = sold + [ hold_id ]
+    unschedule(:expire, key: buyer)
+    { confirmed: true }
+  end
+
+  def expire(buyer:, hold_id:, expires_at:)
+    return seats_available unless holds[buyer] == { "hold_id" => hold_id, "expires_at" => expires_at }
+
+    self.holds = holds.except(buyer)
+    self.seats_available += 1
+  end
+
+  def update_details(title:, base_revision:)
+    reject(:stale_revision, "Reload the event and try again") unless base_revision == revision
+
+    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