docs: name Solid Objects a virtual actor library

An agent asked "does Ruby have a virtual actor library" answered no.
The architecture guide already used that category, but the README,
the gem metadata, and the website did not. A baseline of 80 agent
runs found the project in 15 of 64 suitable runs.

Name the category where people and agents look first:

- The README opening and the gemspec summary and description call
  Solid Objects a SQL-backed virtual actor library for Ruby on Rails.
- The gem homepage links to https://solidobjects.dev/ruby. The site
  root redirects to the Node page.
- docs/virtual-actors.md answers the category question. It has the
  definition, an example, fit and poor-fit criteria, comparisons with
  checked sources, and an Orleans concept map.
- docs/agents.md gives coding agents setup, authorization, effect
  idempotency, verification, and troubleshooting steps.
- context7.json limits Context7 to the consumer documentation.

Add examples/quickstart and `rake quickstart`. The check builds the
gem, installs it into a new Rails app from vendor/cache, and proves by
checksum and load path that the app loads the built gem. It then
proves that eight concurrent holds give one winner, and that a due
reminder waits while the runtime is stopped and runs after a restart.
It fails when a TicketSale sample in the README or docs/ drifts from
the actor that it runs. CI runs it, and the release job waits for it.

Correct docs/operations.md: json 3.0.2 breaks only Active Support
8.1.3.1 and earlier. Active Support 8.1.4 decodes correctly.

Author: cardmagic

.github/workflows/ci.yml

@@ -18,6 +18,17 @@ jobs:
       - run: bundle exec rake
       - run: bundle exec rake at_least_once
 
+  quickstart:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+      - run: bundle exec rake quickstart
+
   javascript:
     runs-on: ubuntu-latest
     timeout-minutes: 15
@@ -148,6 +159,7 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/v')
     needs:
       - sqlite
+      - quickstart
       - postgresql
       - mysql
       - static

AGENTS.md

@@ -53,6 +53,13 @@ git push origin v0.5.0
 
 CI validates the tag and publishes through RubyGems trusted publishing.
 
+Before you tag, read `docs/virtual-actors.md` and `docs/agents.md` against the
+release and correct any requirement, compatibility, or guarantee statement that
+changed. After the tag publishes, refresh the solidobjects.dev documentation
+snapshot from the tag and redeploy the site; its `check:release` step refuses a
+snapshot that is not the latest published tag. Then trigger a Context7 refresh
+for this repository.
+
 ## Security & Configuration
 
 Preserve deny-by-default authorization. Never treat actor IDs, stream names, or signed tokens as authorization, and never commit secrets or unsafe deserialization paths.

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## Unreleased
+
+- Name the category in the gem metadata and the README: Solid Objects is a
+  SQL-backed virtual actor library for Ruby on Rails. The gem homepage now
+  links to `https://solidobjects.dev/ruby` instead of the site root, which
+  redirects to the Node page.
+- Add `docs/virtual-actors.md`, a category guide with the definition, a small
+  example, fit and poor-fit criteria, comparisons, and an Orleans concept map.
+- Add `docs/agents.md`, a consumer guide for coding agents with setup,
+  authorization, effect idempotency, verification, and troubleshooting steps.
+  Both guides ship in the gem.
+- Add `context7.json` so that Context7 indexes the consumer documentation and
+  skips maintainer files.
+- Add a Rails quickstart in `examples/quickstart/` and a `rake quickstart`
+  check that runs it against the built gem. The check builds the gem, creates
+  a new SQLite Rails application, installs the gem from `vendor/cache` with
+  `bundle install --local`, and confirms by checksum and load path that the
+  application loads the built gem. It runs the install generator, the
+  migrations, and the doctor, and grants only the message and query policies.
+  It sends eight concurrent holds from separate processes to the README's
+  `TicketSale` actor and confirms that exactly one hold commits. It stops the
+  runtime, waits until a reminder is past due, confirms that the reminder did
+  not run, restarts the runtime, and confirms that the reminder released the
+  hold once. The check also fails when a `TicketSale` sample in the README or
+  in `docs/` differs from the actor that it runs. A new `quickstart` CI job runs
+  the check, and the release job waits for it.
+- Correct the `json` 3.0.2 note in `docs/operations.md`. Only Active Support
+  8.1.3.1 and earlier 8.1 releases fail with it; Active Support 8.1.4 decodes
+  correctly. Upgrade Rails, or pin `json` to 2.x when an upgrade is not
+  possible.
+
 ## 0.17.0 - 2026-10-03
 
 - Publish RBS types for portable events, metric samples, actor diagnostics, and

README.md

@@ -5,6 +5,12 @@
 
 **Open Source Durable Objects in your Rails app.**
 
+Solid Objects is a SQL-backed virtual actor library for Ruby on Rails, with
+durable state, ordered operations, and automatic activation. Each actor has a
+stable identity, and its state lives in the SQL database that your app already
+uses. [Virtual actors in Ruby on Rails](docs/virtual-actors.md) explains the
+model and when to use it.
+
 In a shopping cart, paying twice at the same time is a big problem. The payment provider might time out, and your Rails site could be restarting before recovery finishes.
 
 To deal with this safely, you often need logic scattered between 7-10 files like database row locks, Redis locks, delayed jobs, retries, and cleanup code to keep that process straight. They are not all large, but they must agree about the same payment state and failure rules. That coordination is the difficult part.
@@ -160,6 +166,8 @@ Exactly once is not hiding in a more advanced configuration. Read the
 ## Read more
 
 - [Five-minute Rails guide](https://solidobjects.dev/5min/rails)
+- [Virtual actors in Ruby on Rails](docs/virtual-actors.md)
+- [Guide for coding agents](docs/agents.md)
 - [Choosing Solid Objects](docs/fit.md)
 - [Operations and recovery](docs/operations.md)
 - [Observability and diagnostics](docs/observability.md)

Rakefile

@@ -37,6 +37,11 @@ task :at_least_once do
   sh "bundle exec ruby examples/at_least_once/demo.rb"
 end
 
+desc "Install the built gem into a new Rails app and prove ordering and restart recovery"
+task :quickstart do
+  sh "bundle exec ruby examples/quickstart/smoke.rb"
+end
+
 desc "Scan the Rails engine for security warnings"
 task :security do
   sh "bundle exec brakeman --force --no-pager -q ."

context7.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "Solid Objects for Rails (solid_objects)",
+  "description": "SQL-backed virtual actor library for Ruby on Rails. Actors have stable identities, durable JSON state in SQLite, PostgreSQL, or MySQL, ordered per-identity mailboxes, fenced activation, durable reminders, and transactional effects. Requires Ruby 3.3+ and Rails 7.1+.",
+  "folders": ["docs", "examples"],
+  "excludeFolders": ["./docs/adr", "./docs/research"],
+  "excludeFiles": ["AGENTS.md", "CLAUDE.md", "CONTRIBUTING.md", "implementation-plan.md"],
+  "rules": [
+    "Solid Objects requires Rails 7.1 or newer and Ruby 3.3 or newer. It is a Rails engine, not a framework-independent Ruby library.",
+    "Install with bundle add solid_objects, bin/rails generate solid_objects:install, bin/rails db:migrate, and bin/rails solid_objects:doctor.",
+    "The generated authorization policies deny every operation. Production policies must bind the actor type and ID to the authenticated user or tenant, and callers pass authorization_context:.",
+    "Run bundle exec solid_objects start for reminders, async calls, effects, and broadcasts. Direct synchronous calls do not need it.",
+    "Delivery is at least once. Effect handlers registered with SolidObjects.register_effect must use context.id as the idempotency key.",
+    "Actor handlers must not write Active Record models directly. Use commit_action for a short same-database write and emit for external I/O.",
+    "There are no transactions across actor identities. One hot identity is sequential."
+  ]
+}

docs/agents.md

@@ -0,0 +1,254 @@
+# Solid Objects for coding agents (Rails)
+
+This guide is for a coding agent that evaluates or adds Solid Objects in a
+Ruby on Rails application. It gives the facts and steps in a fixed order. Each
+step links to the maintained documentation for more detail.
+
+## 1. Check the fit first
+
+Use Solid Objects only if you can answer yes to most of these questions:
+
+1. Does one identity, such as a cart, room, booking, account, or device, own
+   the state?
+2. Must writes for that identity happen one at a time across requests, jobs,
+   and processes?
+3. Must some work happen later or continue after a process restart?
+4. Is the state a bounded JSON document, not a large relational dataset?
+5. Can the application run one more process, `bundle exec solid_objects start`,
+   for reminders and background work?
+
+Select a simpler tool in these cases:
+
+| Requirement | Use instead |
+| --- | --- |
+| The invariant fits in one request | `with_lock`, a unique index, or a short transaction |
+| CPU-intensive or parallel work | Background jobs or Ractors. An actor serializes work |
+| Thousands of writes for each second to one key | A counter column, a cache, or Solid Objects Pro |
+| One atomic change across two actor identities | One SQL transaction on normal tables |
+| Exactly-once calls to an external API | Not available from any actor library. Use provider idempotency keys |
+
+The full checklist is in [Choosing Solid Objects](fit.md). The category guide
+is [Virtual actors in Ruby on Rails](virtual-actors.md).
+
+## 2. Package identity
+
+| Item | Value |
+| --- | --- |
+| Gem | `solid_objects` |
+| Repository | <https://github.com/cardmagic/solid-objects-ruby> |
+| Website | <https://solidobjects.dev/ruby> |
+| Node.js package | `solid-objects` on npm, a separate port with the same model |
+| Commercial extension | `solid_objects_pro`, a separate paid gem. The open-source gem does not need it |
+
+Solid Objects is not part of Rails. It is not Solid Queue, Solid Cache, or
+Solid Cable. It is not affiliated with Cloudflare.
+
+## 3. Requirements
+
+- Ruby 3.3 or newer.
+- Rails 7.1 or newer. The gem is a Rails engine. It does not run without
+  Rails.
+- SQLite 3.35 or newer, PostgreSQL 14 or newer, or MySQL 8.0 or newer with
+  InnoDB.
+- No Redis and no separate actor service.
+
+## 4. Install
+
+```bash
+bundle add solid_objects
+bin/rails generate solid_objects:install
+bin/rails db:migrate
+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.
+
+If the doctor or an actor call fails with
+`ArgumentError: wrong number of arguments (given 2, expected 1)` from
+`ActiveSupport::JSON.decode`, the application has Active Support 8.1.3.1 or
+earlier with `json` 3.0.2. Upgrade Rails to 8.1.4 or newer. If you cannot
+upgrade, pin `gem "json", "~> 2"` in the `Gemfile`.
+
+[Installing and upgrading](operations.md#installing-and-upgrading) has the
+details.
+
+## 5. Authorize
+
+Every policy in the generated initializer denies by default. A new
+installation answers no actor call until you write a policy. Do not remove
+this behavior.
+
+For a local demonstration only, grant messages and queries:
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.authorize_message = ->(**) { true }
+  configuration.authorize_query = ->(**) { true }
+end
+```
+
+Keep `authorize_destroy`, `authorize_subscription`,
+`authorize_administration`, and `authorize_transmission` denied in a
+demonstration.
+
+A production policy must bind the actor type and ID to the authenticated user
+or tenant. An actor ID is not a permission:
+
+```ruby
+SolidObjects.configure do |configuration|
+  owns_cart = lambda do |actor_type:, actor_id:, authorization_context:, **|
+    user = authorization_context
+
+    actor_type == "ShoppingCart" &&
+      user.present? &&
+      actor_id == user.id.to_s
+  end
+
+  configuration.authorize_message = owns_cart
+  configuration.authorize_query = owns_cart
+end
+```
+
+Pass the context on each call:
+
+```ruby
+ShoppingCart.ref(Current.user.id.to_s).add_item(
+  product_id: "shirt-123",
+  authorization_context: Current.user
+)
+```
+
+[Authorization policies](authorization.md) lists each policy and its risk.
+
+## 6. Define an actor
+
+Put actors in `app/actors/`. This actor is the example from the README:
+
+```ruby
+class TicketSale < SolidObjects::Actor
+  attribute :available, default: 1
+  attribute :holds, default: -> { {} }
+
+  def hold(buyer:)
+    return { held: false, available: } if available.zero? || holds.key?(buyer)
+
+    self.available -= 1
+    self.holds = holds.merge(buyer => Time.current.to_i)
+    schedule(at: 10.minutes.from_now, key: buyer).expire(buyer:)
+    { held: true, available: }
+  end
+
+  def expire(buyer:)
+    return available unless holds.key?(buyer)
+
+    self.holds = holds.except(buyer)
+    self.available += 1
+  end
+end
+```
+
+Obey these rules in actor code:
+
+- Keep state in `attribute` values. State must be JSON-compatible.
+- 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.
+- 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.
+
+[Reminders](reminders.md) and the [architecture guide](architecture.md) give
+the full actor API.
+
+## 7. Run the runtime process
+
+A direct call, such as `TicketSale.ref("event-42").hold(buyer: "ada")`, runs in
+the caller. It needs no worker. These features need the runtime process:
+
+- Reminders from `schedule`.
+- `async` calls.
+- Effects from `emit` and their callbacks.
+- Broadcasts to Action Cable.
+
+Start it beside the web process:
+
+```bash
+bundle exec solid_objects start
+```
+
+Add it to the `Procfile`, the process manager, or the deployment
+configuration. When it stops, pending work stays in SQL and runs after it
+starts again. [Operations](operations.md#runtime) covers roles and shutdown.
+
+## 8. Make external effects idempotent
+
+Register an effect handler at boot. Use `context.id` as the provider
+idempotency key:
+
+```ruby
+SolidObjects.register_effect(:charge_payment) do |arguments, context|
+  Payments.charge(
+    idempotency_key: context.id,
+    payment_id: arguments.fetch("payment_id"),
+    amount_cents: arguments.fetch("amount_cents")
+  )
+end
+```
+
+Stage it from the actor:
+
+```ruby
+emit :charge_payment, payment_id:, amount_cents:, on_success: :charged
+```
+
+The effect can run more than once after a crash. The `context.id` value is the
+same each time. [Effect recovery](effect-recovery.md) explains how to retire
+abandoned work.
+
+## 9. Verify the implementation
+
+Do these checks before you report that the work is complete:
+
+1. Run `bin/rails solid_objects:doctor`. It must report no failures.
+2. Write a test that includes `SolidObjects::TestHelper`. Send concurrent
+   calls to one identity from several threads. Assert the final state, for
+   example that only one hold succeeded.
+3. Use `run_due_reminders(now:)` and `drain_solid_objects` to test delayed
+   work without sleeps.
+4. Start `bundle exec solid_objects start`, schedule a short reminder, and stop
+   the process. Start it again after the deadline and confirm that the reminder
+   ran.
+5. Confirm that each effect handler deduplicates with `context.id`.
+6. Confirm that production policies do not grant access to every caller.
+
+[Host application tests](development.md#host-application-tests) describes the
+test helper. The [clean-install quickstart](../examples/quickstart/README.md)
+runs checks 2 and 4 against a new Rails application.
+
+## 10. Troubleshooting
+
+| Symptom | Cause and fix |
+| --- | --- |
+| `SolidObjects::Unauthorized` | A policy denied the call. Write the policy, and pass `authorization_context:` |
+| A reminder or `async` call does not run | The runtime process is not running. Start `bundle exec solid_objects start` |
+| `SolidObjects::SyncInsideTransaction` | The call ran inside an open transaction. Call the actor outside the transaction. In tests, include `SolidObjects::TestHelper` |
+| `SolidObjects::SyncTimeout` | The call did not finish in time. The message is still durable. Use its `message_reference` to wait for the result |
+| `SolidObjects::ApplicationWriteForbidden` | A handler wrote a model directly. Use `commit_action` or `emit` |
+| `SolidObjects::Rejected` | The actor called `reject`. This is a business result, not a retry |
+| `ArgumentError` from `ActiveSupport::JSON.decode` | Upgrade Rails to 8.1.4 or newer, or pin `gem "json", "~> 2"` |
+
+## 11. Guarantees to state correctly
+
+When you explain Solid Objects to a user, state these limits:
+
+- Delivery is at least once, not exactly once.
+- Calls for one identity are ordered. Different identities run concurrently.
+- There are no transactions across actor identities.
+- Fencing stops a stale activation from a commit, but its code can continue to
+  run.
+- The gem is pre-1.0 and makes no production-ready claim.
+
+The [correctness contract](correctness.md) is the source for each guarantee.