solid_objects 0.17.0 → 0.17.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27c3d17cf47d0d22b069ed5fbddfb948495fd1c62ef807e43d0f271511a63ea8
-  data.tar.gz: 1161d2b5f269a22f9b509e73a0cacc8f46c0a0528bb7e54be9c2fdf81ad0055b
+  metadata.gz: 5e79dde8294572943d3d728fb8a6a5e4e334a15ee8645ccd46c0ab2914c538da
+  data.tar.gz: 82550704291588ebbdd3ea2ba0579f02807ecfa2835ce2c25202fcfdf9443cca
 SHA512:
-  metadata.gz: f9ae16fca8e08fd41806a22a9a7f27904d0492870e52a9f1b4b9d9ca3bb6f95b85d965fd9b40e82ddc3154334564067ba36d090a8379e71c111c5dc043a0ce66
-  data.tar.gz: 93e89b4878dac64ed92ebc50361720bf0c43a713ef069be0f5f4988bad29045cc6ca8c1aeb857510fe7830b6e6df0a3f4a5a2cbc503dedea56a4177b15b7af36
+  metadata.gz: 22f3ad5fe3c144a424cf74936780ab2196536b1d0c46ae71c47a14aef92f6815d842f43f791f398640f63651c0be5b473f715d3a008c00992a7995d78c7cfc5a
+  data.tar.gz: e678f2c1d603407b7f6d113d7a1c440f25e4481c300a2c040873883172979621823517cf341ec3128484a2ef7d683c485d69e6dcc550dffde62826aeb6a1d6cd

data/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 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
+  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.x note in `docs/operations.md`. The `json` gem 3.x works
+  only with Active Support 8.1.4 or newer. Active Support 7.1, 7.2, and 8.0
+  raise `unknown keyword: quirks_mode`, and Active Support 8.1.3.1 and earlier
+  8.1 releases fail to decode. Upgrade Rails to 8.1.4 or newer, or pin `json`
+  to 2.x. The compatibility CI matrix now pins `json` 2.x for Rails 7.1, 7.2,
+  and 8.0, the configuration that the guide prescribes.
+
 ## 0.17.0 - 2026-10-03
 
 - Publish RBS types for portable events, metric samples, actor diagnostics, and

data/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.
@@ -38,7 +44,8 @@ And so much more.
 
 ## 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
@@ -160,6 +167,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)

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

data/docs/agents.md

@@ -0,0 +1,273 @@
+# 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.
+
+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
+`unknown keyword: quirks_mode`, for every JSON column.
+
+[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.
+  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.
+
+## 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`, such as `unknown keyword: quirks_mode` | `json` 3.x with Active Support before 8.1.4. 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.

data/docs/operations.md

@@ -26,22 +26,24 @@ reports a failed or warned check rather than raising out of the command.
 ## Installing and upgrading
 
 Solid Objects keeps actor state, message arguments, results, and the remembered
-idempotency keys in JSON columns. Active Support decodes every one of them, and
-`ActiveSupport::JSON.decode` raises with the `json` gem at 3.0.2:
+idempotency keys in JSON columns. Active Support encodes and decodes every one
+of them. The `json` gem 3.x works only with Active Support 8.1.4 or newer:
 
-```
-ArgumentError: wrong number of arguments (given 2, expected 1)
-```
+- Active Support 7.1, 7.2, and 8.0 raise
+  `ArgumentError: unknown keyword: quirks_mode` when they encode or decode.
+- Active Support 8.1.3.1 and earlier 8.1 releases raise
+  `ArgumentError: wrong number of arguments (given 2, expected 1)` when they
+  decode.
 
 The failure is in Active Support rather than in Solid Objects, and it reaches
-every JSON column in a Rails application. A new Rails 8.1 application resolves
-`json` 3.0.2 today, so pin the 2.x series until Rails ships a fix:
+every JSON column in a Rails application. Upgrade Rails to 8.1.4 or newer. On
+an older Rails release, pin the 2.x series of `json`:
 
 ```ruby
 gem "json", "~> 2"
 ```
 
-Review [CHANGELOG.md](CHANGELOG.md) for compatibility and deployment-order
+Review [CHANGELOG.md](../CHANGELOG.md) for compatibility and deployment-order
 notes, then update the gem:
 
 ```bash

data/docs/virtual-actors.md

@@ -0,0 +1,226 @@
+# Virtual actors in Ruby on Rails
+
+## Short answer
+
+Yes. Solid Objects is a SQL-backed virtual actor library for Ruby on Rails.
+The gem is `solid_objects`. It gives each actor a stable identity, durable
+state, ordered operations, and automatic activation.
+
+Solid Objects requires Rails. It is a Rails engine for Ruby 3.3 or newer and
+Rails 7.1 or newer. It is not a framework-independent Ruby actor runtime.
+State and mailboxes live in the SQLite, PostgreSQL, or MySQL database that the
+Rails application already uses. Redis and a separate actor service are not
+necessary.
+
+Solid Objects is a pre-1.0 release. It makes no production-ready claim. Read
+[Compatibility and maturity](#compatibility-and-maturity) before you choose it.
+
+## What a virtual actor is
+
+A virtual actor is a logical object that always exists by name. The caller
+does not create it, start it, or stop it. The runtime loads it when a message
+arrives and releases it when it is idle. Microsoft Orleans made this model
+known as "virtual actors".
+
+Solid Objects implements four properties of that model:
+
+| Property | What it means | How Solid Objects does it |
+| --- | --- | --- |
+| Stable identity | An actor is addressed by type and ID, for example one cart per user. | `ShoppingCart.ref(user.id)` returns a cheap reference. The reference does not load the actor. |
+| Automatic activation | The first message activates the actor. An idle actor is released. | A process claims a fenced activation lease when work arrives. The lease is released after the idle timeout. |
+| Durable state | State survives process restarts and deploys. | Actor attributes are a JSON document in the application database. |
+| Ordered turns | One identity runs one operation at a time, in a fixed order. | Each call is a durable mailbox message with a per-actor sequence number. |
+
+Different identities run concurrently. One identity is a serialization point
+on purpose.
+
+## A small example
+
+This actor holds one ticket for a buyer and releases the hold after ten
+minutes. Put it in `app/actors/ticket_sale.rb`:
+
+```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
+```
+
+Call it from a controller, a job, or the console:
+
+```ruby
+TicketSale.ref("event-42").hold(buyer: "ada")
+```
+
+Two concurrent `hold` calls for `event-42` enter the same mailbox. They commit
+one at a time, so only one buyer gets the ticket. The hold and its reminder
+commit in one transaction. The reminder runs in the Solid Objects runtime
+process:
+
+```bash
+bundle exec solid_objects start
+```
+
+If that process stops, the reminder stays in SQL. It runs when the process
+starts again.
+
+The example needs installation, migrations, and an authorization policy. The
+generated policies deny every operation by default. For the complete setup,
+use one of these guides:
+
+- [Installation](../README.md#installation) in the README.
+- [The clean-install quickstart](../examples/quickstart/README.md), which a
+  smoke check runs against the built gem in a new Rails application.
+- [The agent guide](agents.md), which gives setup and verification steps for
+  coding agents.
+
+## When to use it
+
+Solid Objects is a good candidate when most of these conditions are true:
+
+- State belongs to one durable identity, such as a cart, room, booking,
+  device, account, or workflow.
+- Writes for that identity must be serialized across requests, jobs, and
+  processes.
+- The work must happen later, survive a restart, or stay ordered across more
+  than one request.
+- The state is a bounded JSON document.
+- The identity needs reminders, external effects, or reactive Rails views that
+  follow its committed state.
+
+## When to use something else
+
+Do not use an actor when a simpler tool enforces the invariant:
+
+- One short transaction, `with_lock`, or a database constraint is enough. A row
+  lock is often the clearest answer.
+- The work is CPU-intensive or data-parallel. An actor serializes work. It does
+  not add CPU parallelism.
+- One hot identity must accept many writes for each second, for example a
+  request-path rate limiter or a page-view counter.
+- The state is large, relational, or query-heavy. Keep that data in normal
+  tables.
+- The operation must change two actor identities in one atomic transaction.
+  Solid Objects has no cross-actor transactions.
+- You need exactly-once calls to an external API. No actor library can promise
+  that through every network failure. Solid Objects gives at-least-once
+  delivery and stable effect IDs for idempotency keys.
+- You need replay of named workflow steps from a step log. That is a durable
+  execution engine, not an actor.
+
+[Choosing Solid Objects](fit.md) has the full checklist and the cost model.
+
+## How it compares
+
+This table compares coordination models for a Rails application. It does not
+rank the projects. Facts about other projects were checked on October 7, 2026,
+against the sources in [Primary references](#primary-references).
+
+| Approach | Unit of order | Durable state | Delayed work | Extra service | Good for |
+| --- | --- | --- | --- | --- | --- |
+| `with_lock` or a short SQL transaction | Rows in one transaction | Application tables | None | No | An invariant that fits in one request |
+| Active Job with Solid Queue | None. `limits_concurrency` limits overlap for each key, but it does not set an order | Application tables, owned by the application | Scheduled jobs | No; Solid Queue uses the database | Background work that does not own entity state |
+| Sidekiq | None in the open-source gem. Unique jobs and rate limits are Sidekiq Enterprise features | Application tables, owned by the application | Scheduled jobs | Redis | High-volume background jobs |
+| In-process concurrency: Ractor, `concurrent-ruby-edge` actors, Async | One Ruby object in one process | None. State is lost when the process stops | In process only | No | Parallel or concurrent work inside one process. Ractor is experimental in Ruby 4.0 |
+| Solid Objects | Actor type and ID | JSON state in the application database | Durable per-actor reminders | No; the `solid_objects start` process runs in the app | Durable per-identity state with ordered operations |
+| Dapr actors | Actor type and ID, one turn at a time | A transactional Dapr state store | Durable reminders through the Dapr Scheduler service | A Dapr sidecar, plus the placement and Scheduler services. Dapr has no official Ruby SDK | Polyglot services on a Dapr platform |
+| Temporal (`temporalio` gem) | A workflow execution | Temporal event history | Durable timers | A Temporal Service, self-hosted or Temporal Cloud | Long-running workflows that replay deterministic code |
+
+### Orleans concept map
+
+Orleans is the reference design for virtual actors on .NET. Solid Objects
+uses the same programming model on a SQL database. It does not copy the
+Orleans cluster, placement, or feature set.
+
+| Orleans | Solid Objects | Difference |
+| --- | --- | --- |
+| Grain class | `SolidObjects::Actor` subclass | None in concept |
+| Grain identity (key) | Actor type and actor ID | None in concept |
+| Activation on first call | Activation lease on first claimed message | Solid Objects fences each activation with a database generation |
+| Turn-based execution | Ordered mailbox, one turn at a time | Orleans can enable reentrancy. Solid Objects turns for one identity never interleave |
+| Grain persistence | JSON attributes in the application database | An Orleans grain calls `WriteStateAsync`. Solid Objects persists state with the turn that changed it |
+| Reminders | `schedule` | Both are durable. Orleans skips a tick that falls due while the cluster is down. A due Solid Objects reminder runs when a runtime process starts. Solid Objects has no non-durable timers |
+| Silos and cluster membership | Any Rails process that runs `solid_objects start` | Solid Objects has no placement, directory, or cluster membership. The database is the coordination point |
+| Streams | Observables, broadcasts, and reactive ERB | Solid Objects delivers committed revisions to Action Cable |
+
+Solid Objects delivery is at least once. Write each handler so that it can run
+again without harm.
+
+## Guarantees and boundaries
+
+- Calls are durably ordered per identity. Different identities can run
+  concurrently.
+- Delivery is at least once, not exactly once. A handler can start again after
+  a crash or a lost lease.
+- Ordered turns do not cancel stale Ruby code. Fencing stops a stale activation
+  from a commit, but that code can continue to run.
+- External effects can run more than once. Use the stable effect ID, or
+  another durable key, as the idempotency key at the provider.
+- There are no transactions across actor identities, and there is no replay of
+  durable function steps.
+- Reminders, `async` calls, effects, and broadcasts need the
+  `bundle exec solid_objects start` process. When that process stops, the work
+  waits in SQL. The gem does not supply a hosted worker.
+- One hot identity is sequential. The core gem is not a high-throughput
+  request-path rate limiter.
+- The guarantees apply only to changes made through the actor APIs. Actor
+  fencing does not protect direct writes to the same data or other external
+  requests.
+
+The [correctness contract](correctness.md) states each guarantee and the crash
+matrix.
+
+## Compatibility and maturity
+
+- Ruby 3.3 or newer and Rails 7.1 or newer. CI runs Ruby 3.3, 3.4, and 4.0
+  against Rails 7.1, 7.2, 8.0, and 8.1.
+- SQLite 3.35 or newer, PostgreSQL 14 or newer, or MySQL 8.0 or newer with
+  InnoDB. MySQL works through `mysql2` or `trilogy`.
+- SQLite is correct for the same contract, but it is best for development and
+  modest single-host workloads.
+- Pre-1.0. Expect changes that break compatibility. The correctness core has tests against all
+  three databases. The project has no production-ready claim and no measured
+  scale claim.
+
+The [roadmap](roadmap.md) records what is tested, what is partial, and what is
+next. For TypeScript and Node.js, use the
+[solid-objects](https://github.com/cardmagic/solid-objects-js) package.
+
+## Primary references
+
+- Orleans: [Overview](https://learn.microsoft.com/en-us/dotnet/orleans/overview),
+  [Request scheduling](https://learn.microsoft.com/en-us/dotnet/orleans/grains/request-scheduling),
+  [Timers and reminders](https://learn.microsoft.com/en-us/dotnet/orleans/grains/timers-and-reminders),
+  [Grain persistence](https://learn.microsoft.com/en-us/dotnet/orleans/grains/grain-persistence/),
+  and [Grain placement](https://learn.microsoft.com/en-us/dotnet/orleans/grains/grain-placement).
+- Ruby: [Ractor](https://docs.ruby-lang.org/en/4.0/Ractor.html) and the
+  [Ruby 4.0.0 release notes](https://www.ruby-lang.org/en/news/2025/12/25/ruby-4-0-0-released/).
+- concurrent-ruby: [repository](https://github.com/ruby-concurrency/concurrent-ruby)
+  and [`Concurrent::Actor`](https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Actor.html).
+- Solid Queue: [concurrency controls](https://github.com/rails/solid_queue#concurrency-controls).
+- Sidekiq: [Enterprise unique jobs](https://github.com/sidekiq/sidekiq/wiki/Ent-Unique-Jobs)
+  and [Enterprise rate limiting](https://github.com/sidekiq/sidekiq/wiki/Ent-Rate-Limiting).
+- Dapr: [Actors overview](https://docs.dapr.io/developing-applications/building-blocks/actors/actors-overview/),
+  [Actor timers and reminders](https://docs.dapr.io/developing-applications/building-blocks/actors/actors-timers-reminders/),
+  and [SDKs](https://docs.dapr.io/developing-applications/sdks/).
+- Temporal: [Ruby SDK](https://github.com/temporalio/sdk-ruby) and
+  [Event History](https://docs.temporal.io/encyclopedia/event-history).
+
+Other projects change. Check these sources again before you base an
+architecture decision on one row.