docs: add four tested problem guides

[cardmagic]

Why

Developers search for a problem ("Rails race conditions", "Sidekiq jobs in order per user", "reserve tickets for 15 minutes", "after_commit job lost"), not for a virtual actor library. These guides answer those problems. Each one shows the plain Rails fix first and recommends Solid Objects only where it adds value. They will be published at /ruby/race-conditions, /ruby/ordered-jobs, /ruby/expiring-reservations, and /ruby/transactional-outbox on solidobjects.dev.

What changed

• docs/guides/race-conditions.md, "Prevent race conditions in Rails".
  • A decision table, then unique indexes, pessimistic locking, and optimistic locking.
  • A ticket-hold example that grows from a reproduced race, to a one-statement SQL fix, to one actor that owns the event. The actor covers holds, confirmation, expiry, retries, a restart, and a stale expiry.
  • A section that says plainly that serial execution does not stop a stale form, and shows a revision check.
• docs/guides/ordered-jobs.md, "Run jobs in order for each customer in Rails".
  • The out-of-order failure.
  • A fair comparison of a Sidekiq capsule with concurrency 1, Solid Queue limits_concurrency, and a sequence number with a row lock.
  • One actor for each account.
• docs/guides/expiring-reservations.md, "Expiring reservations in Rails".
  • The stock goes under the identity that owns it: an actor for each reservation does not stop overselling.
  • The plain SQL design that needs no timer, and when a timer is necessary.
  • Hold, extend, confirm, and expire, with reminders that move and survive a restart.
• docs/guides/transactional-outbox.md, "Save state and queue work together in Rails".
  • The lost job between commit and enqueue, and the plain outbox pattern with Rails Event Store cited.
  • The atomic boundary of an actor turn: state, a commit action, and an effect.
  • A section that says what Solid Objects does not do. It does not wrap ordinary Active Record writes.
• The README and docs/agents.md list the guides.
• Version 0.17.3 and its changelog section.

Code and tests

Every code block in a guide is a file under examples/guides/. The tests in test/guides/ (43 runs) prove each claim the guides make.

test/guides/guide_documents_test.rb fails in three cases: a guide does not embed the current example files verbatim (without the rbs_inline header line), a guide contains U+2013 or U+2014, or a relative link points to a missing file.

Observed failures.

• Red first: each test file was run before its examples existed and failed with LoadError: cannot load such file -- .../examples/guides/.... The document test failed with Errno::ENOENT before the guides existed.
• Removing each guard once: each example guard was removed once, and a test failed every time. The guards were:
  • the conditional update, the hold and confirm retry guards, the stale expiry checks, the revision check, and the reminders;
  • the out-of-sequence raise, the repeated-sequence skip, retry_on, and the entry dedupe;
  • reject (replaced by a raise), the seat check, the extension reschedule and limit, and unschedule;
  • the outbox transaction, the relay mark, the job idempotency key, the place guard, and the effect idempotency key.
• Two tests that passed without their guard were rewritten:
  • The conditional-update test let thread timing hide the race. It now loads every copy first and releases all threads at a barrier.
  • The hold retry test now checks that a retried hold reports success.
• A PostgreSQL deadlock, found and fixed: on PostgreSQL with the default pool of 5, the first concurrency helper failed with could not obtain a connection from the pool within 5.000 seconds. The helper now limits the threads that act at once to the free connections. Each file passed on a fresh local PostgreSQL 17 database. MySQL was not run locally; CI covers it.

Dependency change

activejob joins the development and test group. Compatibility runs pin it with ~> RAILS_VERSION.0, and bundle lock --update --print resolves 7.1.6 and 8.0.5.1 for RAILS_VERSION=7.1 and 8.0. The default lock adds activejob 8.1.3.1 and globalid 1.4.0. No other gem changes. The runtime gemspec is unchanged.

Copy

Codex CLI with GPT-6 Astra (codex exec -m gpt-6-astra, read-only sandbox) wrote the prose from four briefs. The briefs held the outline, the verified facts with sources (checked October 9, 2026), and the ASD-STE100 and no-dash rules. Codex wrote {{EMBED path}} placeholders, and a script replaced them with the exact tested files. Every claim was checked against docs/correctness.md, docs/architecture.md, docs/operations.md, docs/reminders.md, and the cited pages.

Hand edits to the Codex copy.

1. expiring-reservations.md: "An actor for each reservation does not stop two reservations from the same stock." became "An actor for each reservation cannot prevent an oversold show. Two reservations can take the same stock." The verb was missing.
2. All four guides: "## Related reading" became "## More information", because STE does not use an -ing form.
3. race-conditions.md: "SQL retains pending work" became "SQL keeps the unfinished work".

Citations, all checked October 9, 2026:

• Rails Guides on uniqueness validation and on enqueue_after_transaction_commit.
• The Rails API pages for pessimistic and optimistic locking.
• The Solid Queue README section on concurrency controls.
• The Sidekiq wiki section on capsules.
• The Rails Event Store outbox documentation.

Effects

• API, correctness, migration: none. These are documentation, examples, and tests only.
• Security: none. The guides keep deny-by-default authorization and tell the reader to pass authorization_context:.
• Compatibility: the examples target Ruby 3.3+ and Rails 7.1+.

Validation

• bundle exec rake: 916 runs, 0 failures, 0 errors, 28 skips. Standard Ruby and RuboCop found no offenses in 301 files. RBS validates, Steep found no type errors, and Brakeman found no warnings.
• bundle exec ruby -Itest test/guides/<file> for each guide test against SOLID_OBJECTS_DATABASE_URL=postgresql://localhost/solid_objects_guides_test (a fresh database for each file): every file passed.

[context7]

Docs7 for cardmagic/solid-objects-ruby

Result	Status	Action
Deployment	➖ Not used	—
Content review	❌ Needs attention. 1 problem remains.	View findings

Commit 8f077a1

1 finding is inline on the changed files.

[greptile-apps]

Confidence Score: 5/5

[Low impact] The PR appears safe to merge; the stale expiry finding is fixed, and no new blocking issue was found.

Summary

Adds four Rails problem guides with matching examples and tests.

• Rails developers can compare simple race fixes with an actor-run ticket lifecycle.
• Rails developers can compare job-order options and follow one account's entries in order.
• A show actor keeps seat holds, confirmations, and expiry reminders together.
• Rails developers can compare an outbox with an actor turn that saves state and shipment work together.
• Project listings and test setup now include the new guides.

No new actionable issues were found. Previous comment 1 is fully addressed.

_{Reviews (3) · Last reviewed commit: "ci: pull database images from the ECR Pu..." · Reviewed by Greptile}

[cardmagic]

@greptileai Please review the latest commit, bc462f4. It addresses each finding:

1. Expired holds still succeed: fixed in both actors. EventTickets and SeatInventory store each deadline. confirm and extend_hold accept only a hold whose deadline is in the future, and an expired hold frees its seats before the reminder runs. The reminder only cleans up. New tests use travel past the deadline and deliver no reminder. Both failed before the change.
2. Negative holds inflate stock: fixed. hold rejects a seat count that is not a positive integer with invalid_seats. A new test covers 0 and -5. It failed before the change.
3. Older entries change balances twice: fixed with a durable record. Each entry writes a ledger_entries row through the commit action record_ledger_entry, in the same transaction as the balance. The table has a unique index on account and entry. apply checks LedgerEntry.exists? first, which is safe because calls for one account run one at a time. A new test applies 102 entries and then repeats the first. It failed before the change. The guide now says the 64-key idempotency window is not enough for money.
4. Unused configuration remains: removed the commented-out weighted line from the Sidekiq snippet.

The commit also fixes two Rails 7.1 and 7.2 test failures from CI:

• The lost-job test now replaces perform_later, because ActiveJob::TestHelper on Rails 7.1 and 7.2 ignores an adapter assigned inside the test.
• The two-worker test creates its workers before the threads start, so two process registrations no longer race on SQLite.

Validation:

• bundle exec rake: 920 runs, 0 failures, 28 skips. No offenses, no type errors, no Brakeman warnings.
• The guide tests pass on a fresh local PostgreSQL 17 database and on Rails 7.1.6 with SQLite. The ordered-jobs test passed 5 of 5 times on 7.1.

[cardmagic]

@greptileai Please review the latest commit, 8f077a1.

• Old expiry cancels new hold (8919831): fixed as you suggested. The reminder passes the stored deadline, expire(buyer:, hold_id:, expires_at:), and expire releases a seat only when the hold ID and the deadline both match, as in SeatInventory. A new test retries with the same hold ID after the deadline, then delivers the old expiry, and the fresh hold stays. With the deadline check removed, the test fails. The guide text and its test list describe this.
• 8f077a1 moves the CI service images to the ECR Public mirror (public.ecr.aws/docker/library/redis:7, postgres:18, and mysql:8.4), because GitHub runners hit the Docker Hub pull rate limit.

Validation: bundle exec rake ran 921 runs with 0 failures and 28 skips. Standard Ruby, RuboCop, Steep, and Brakeman are clean.

[context7]

Grammar and spelling: After the bold colon the sentence starts with a lowercase 'the'; capitalize it like the other bullets.