solid_objects 0.16.1 → 0.17.1

data/docs/observability.md

@@ -0,0 +1,186 @@
+# Portable observability
+
+Configure `instrumentation(event)` to receive structured events. No exporter SDK
+is required. The same JSON envelope is emitted by Ruby, SQLite, PostgreSQL, MySQL,
+and the Durable Objects host. Existing JavaScript `name`, `occurredAt`, and
+`attributes` fields remain available. Ruby's Active Support notifications remain
+available with their existing snake_case payloads.
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.instrumentation = ->(event) do
+    Rails.logger.info(JSON.generate(event))
+  end
+end
+```
+
+JavaScript passes `instrumentation` to `configure()`. Ruby sets
+`configuration.instrumentation` inside `SolidObjects.configure`.
+
+## Schema version 1
+
+Every event has `schemaVersion`, `name` (prefixed with `solid_objects.`),
+`occurredAt` (UTC ISO 8601), `adapter`, `actorType`, `actorId`, `incarnation`,
+`revision`, `messageId`, `attempt`, `attributes`, and `metrics`.
+Unavailable identifiers are null; `attempt` is zero outside a message attempt.
+Ruby publishes the RBS types `SolidObjects::portable_event`,
+`SolidObjects::actor_diagnostics`, and `SolidObjects::event_observer`. JavaScript
+exports `InstrumentationEvent`, `ActorDiagnostics`, and `EventObserver`.
+An incarnation identifies a persisted actor instance, independently of its lease
+generation. Revisions and IDs are strings. Process-wide events have null actor
+identity. A message ID or revision correlates actor work where applicable.
+
+Only known scalar metadata fields enter the portable envelope. Arguments, state,
+results, credentials, backtraces, exception text, nested provider data, and unknown
+attributes are excluded. Actor IDs remain correlation data: applications should
+use opaque actor identifiers and apply their own retention policy to event logs.
+Events and metric samples are immutable. Throwing observers, rejected observer
+promises, and a failing instrumentation error logger cannot change a turn's
+result. When an exporter or observer raises, both runtimes log
+`solid_objects.instrumentation.failed` with the event name and the error class.
+Delivery is best effort and synchronous callbacks should be short;
+JavaScript does not await exporters. Telemetry is not a durable audit trail.
+
+| Event                                       | Meaning                                                                      |
+| ------------------------------------------- | ---------------------------------------------------------------------------- |
+| `activation.started/completed/failed`       | Local actor activation hook lifecycle                                        |
+| `message.started/completed/failed/rejected` | One attempt's execution outcome                                              |
+| `message.retry`                             | Failed attempt durably queued for another attempt                            |
+| `dead_letter.created`                       | Message exhausted retries or failed permanently                              |
+| `commit_action.started/completed/failed`    | One registered commit action inside the commit transaction                   |
+| `mailbox.depth`                             | On-demand diagnostic sample; `depth` is null when the sample is truncated    |
+| `reminder.enqueued`                         | Due reminder dispatch; lateness is measured from due time                    |
+| `outbox.age`                                | Delivery observation; age is time since the item's current availability time |
+| `recovery.reclaimed`                        | A previously claimed, interrupted message begins another attempt             |
+| `recovery.completed/failed`                 | Durable effect recovery callback commits or enters the dead-letter queue     |
+| `snapshot.read`                             | Authorized snapshot constructed without exposing its contents                |
+| `realtime.connected/disconnected`           | Actor subscription added or removed                                          |
+| `payload_broadcast.failed`                  | One personalized payload failed; `payload` names it                          |
+
+Events describe local observations. Concurrent deletion, crashes, and failed
+exporters can omit events. Never infer exactly-once delivery from event counts.
+Additional existing runtime events retain their names.
+
+## Event attributes
+
+`compatibility/telemetry-events.json` holds the attribute allowlist and the exact
+attribute keys of each core event. Both test suites compare the events of the SQL
+runtimes with this file. Message events carry `operation` and `deliveryMode`.
+`message.failed` also carries a boolean `retryable` and an `outcome` of
+`retrying` or `dead`. Commit action events carry `commitAction` and
+`activationGeneration`. Activation events carry `generation` and `ownerId`.
+
+Ruby activates an actor instance before it claims a message, so its activation
+events have no message fields. JavaScript activates an actor in the turn that
+claims a message, so its activation events also carry the `messageId`,
+`requestId`, `sequence`, `attempt`, `operation`, and `deliveryMode` of that
+message. The contract file records these keys as JavaScript-only.
+
+The Durable Objects host sends the same envelope, but some of its events carry
+fewer attributes. The contract file does not apply to that host.
+
+Portable `polling.interval_changed` events carry `previousIntervalMilliseconds`,
+`currentIntervalMilliseconds`, and a string `reason`. Ruby converts its native
+second-based notification values while preserving the original notification.
+
+## Synchronous timeout diagnostics
+
+`solid_objects.sync.timeout` includes `waitingOn`, `activationOwnerId`, and
+`activationGeneration` in `attributes`. Generations are decimal strings;
+unavailable activation fields are null. Both runtimes use the same wait reasons:
+`actorPaused`, `activationHeld`, `earlierMessage`, `messageClaimed`,
+`notYetAvailable`, `readyUnclaimed`, `databaseContention`, and `unknown`.
+Ruby's exception attributes and Active Support notifications retain their native
+snake_case names and reason values. The portable instrumentation envelope uses
+the shared camelCase contract. The Durable Objects host does not send
+`sync.timeout`. A `call` timeout there reports `waitingOn: "unknown"`.
+
+## Metrics and tracing
+
+Metrics are sample descriptions. Exporting them is opt-in: the runtime does not
+register meters, allocate per-actor metric series, or install a vendor SDK.
+
+| Name                              | Kind      | Unit | Aggregation                                            |
+| --------------------------------- | --------- | ---- | ------------------------------------------------------ |
+| `solid_objects.events`            | counter   | `1`  | Sum one per event                                      |
+| `solid_objects.duration`          | histogram | `ms` | Distribution of observed attempt duration              |
+| `solid_objects.reminder.lateness` | histogram | `ms` | Distribution of reminder dispatch delay                |
+| `solid_objects.outbox.age`        | histogram | `ms` | Distribution of delivery delay since availability      |
+| `solid_objects.mailbox.depth`     | gauge     | `1`  | Last exact sampled actor depth; omit truncated samples |
+
+Labels contain only event name, adapter family, and declared actor type. Keep the
+actor type registry finite. Never add actor ID, incarnation, message ID, operation
+arguments, request IDs, or error text to metric labels. A gauge without an actor
+label represents the most recently observed actor; it is not total fleet backlog.
+For tracing, correlate start/outcome events using `adapter`, `incarnation`,
+`messageId`, and `attempt`, and close or expire spans when no outcome arrives.
+
+## Actor observers and diagnostics
+
+```ruby
+cart = ShoppingCart.ref("demo-cart")
+stop = cart.observe(authorization_context: operator) do |event|
+  logger.info(event.to_json)
+end
+summary = cart.diagnostics(authorization_context: operator, limit: 50)
+stop.call
+```
+
+Ruby uses `reference.observe(authorization_context:) { |event| ... }` and
+`reference.diagnostics(authorization_context:, limit: 50)`. Stop observing by
+calling the returned proc. `on` filters one event name, such as `message.retry`.
+Observers receive only this actor's events in the current runtime/process; they
+are not subscriptions to workers on other hosts. Dispose them when the caller's
+session ends or authorization is revoked. Each runtime or process accepts at most
+1,000 local observers. More observers raise `RangeError` in JavaScript and
+`ArgumentError` in Ruby. An observer needs a callback or a block. JavaScript
+rejects a missing `onEvent` with `TypeError`, and Ruby raises `ArgumentError`
+without a block. Both checks run before authorization.
+
+The JavaScript Durable Objects host does not support process-local reference
+observers. On that host, `observe` and `on` raise `UnsupportedCapability`, and
+remote `reference.diagnostics` works. To observe a remote actor, configure
+`instrumentation` on the actor host and filter the events by actor identity.
+Ruby has no Durable Objects host.
+
+Both APIs default to denied. Set `authorizeAdministration` / `authorize_administration`
+to allow action `observe` or `inspect`, resource `actor_diagnostics`, and resource ID
+`JSON.stringify([actorType, actorId])`. Ruby receives a symbol action. Authorization
+runs before reading summaries or registering observers; possessing an actor ID
+confers no permission.
+
+Diagnostics read at most `limit + 1` rows per queue source, with a hard limit
+of 100 rows. Each category returns `sampled`, `truncated`, and
+`oldestAgeMilliseconds`.
+The limit applies to each combined category: one effect plus one broadcast with
+`limit: 1` returns `sampled: 1, truncated: true`, even when both source queries
+returned all their rows. The extra row proves that the category exceeds its cap.
+The last value measures nonnegative time since availability (or terminal failure
+for recovery callbacks); future reminders have zero age. No payloads or row
+identifiers are returned. Samples are observations across several queries,
+not an atomic fleet snapshot. Large queues can still require database scanning;
+the bound limits materialized rows and response size, not query execution time.
+
+Categories are mailbox (ready and claimed), outbox (pending and processing effects
+and broadcasts), reminders (scheduled and paused), retries (failed messages still
+eligible to run), and recoveryFailures (dead internal effect recovery
+callback messages). Durable Objects does not implement process-heartbeat effect recovery;
+its recoveryFailures category is empty. Recovery failures are durable records,
+not a history of transient database or exporter exceptions.
+
+## A query that works across adapters
+
+Write one envelope per line to `events.jsonl`, using the same instrumentation hook
+with SQLite and PostgreSQL. This query reports completed attempts by adapter:
+
+```sh
+jq -s 'map(select(.name == "solid_objects.message.completed"))
+  | group_by(.adapter)
+  | map({adapter: .[0].adapter, completed: length,
+         mean_ms: (map(.attributes.durationMilliseconds) | add / length)})' events.jsonl
+```
+
+A dashboard can chart the event counter by adapter and outcome and the duration,
+reminder lateness, and outbox age distributions using exactly the same fields.
+Compare workloads with the same actor types and sampling policy. Counts measure
+observations and cannot replace a database query for authoritative queue state.

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/realtime.md

@@ -347,8 +347,9 @@ object or array so the wire format stays inspectable.
 A payload is one subscriber's view of one name, so a failure is confined to it.
 A raising block does not reject the subscription, stop the other payload names,
 or stop component refreshes on the same connection. The failure is reported as
-`solid_objects.payload_broadcast_failed` carrying the actor type, actor id,
-payload name, and exception class. The exception message is deliberately not
+`solid_objects.payload_broadcast.failed` carrying the actor type, actor id,
+payload name, and exception class. The Active Support payload names the payload
+`payload_name`; the portable instrumentation event names it `payload`. The exception message is deliberately not
 included: a payload block reads subscriber state, so its message is the one
 place that state could leak into logs.
 
@@ -356,7 +357,7 @@ A revision with a failed payload does not advance the delivery watermark, so a
 transient failure is retried on the next broadcast rather than being recorded as
 delivered. Retries are driven by broadcasts rather than a timer, so a payload
 that fails persistently retries once per actor mutation and reports each
-attempt. A repeating stream of `payload_broadcast_failed` for one `payload_name`
+attempt. A repeating stream of `payload_broadcast.failed` for one `payload_name`
 therefore means a persistent fault in that block, not a one-off; a single event
 that does not recur was transient and has already been recovered.
 

data/docs/reminders.md

@@ -65,7 +65,9 @@ key only decides which alarm is which.
 
 A key must be non-empty, and the name it becomes must fit the 191-character
 column, which is checked on the composed name rather than the key alone so a
-long operation and a short key are caught too.
+long operation and a short key are caught too. JavaScript allows 255 UTF-16 code
+units for the same combined name. These existing schema limits remain different;
+use at most 191 ASCII characters for names shared across runtimes.
 
 The key is separated from the operation by a colon, so an operation may not hold
 one. Otherwise an unkeyed `deliver:item` and a `deliver` keyed `item` would be

data/docs/roadmap.md

@@ -2,8 +2,19 @@
 
 ## Implemented and tested
 
+- Portable telemetry with a shared JSON schema, metric samples, isolated observer
+  callbacks, bounded authorized actor diagnostics, and matching timeout wait
+  reasons and activation metadata. Both test suites check the attribute keys of
+  each core SQL event against `compatibility/telemetry-events.json`. See
+  [observability](observability.md).
+
 - Rails engine, install generator, migration, and CLI
 - Explicit actor registry, references, JSON state, and state migrations
+- Queries, observable projections, and personalized payloads reject state mutation
+  and staged durable work with `QueryMutatedState`, matching JavaScript. Query
+  and observable violations fail terminally; a payload violation is confined to
+  that payload. Shared JSON fixtures preserve reserved property names as ordinary
+  data in both runtimes.
 - Fluent direct synchronous RPC, configured `sync`, and durable `async`
 - Durable message history plus ready/claimed membership tables
 - Concurrent sequence allocation and actor creation. An enqueue finds the
@@ -55,7 +66,9 @@
   subscriber's authorization context, fenced by actor revision, resolved through
   `payload_authorization_context` so the block and `authorize_query` see the
   same subject a controller render passes, and confined so one failing payload
-  cannot reject the subscription or stop its siblings
+  cannot reject the subscription or stop its siblings. Each payload uses an
+  isolated actor from the same committed snapshot, prevents application database
+  writes, and enforces the configured `max_payload_bytes` limit
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
   migration cookbook. The doctor names every column that a migration after the
@@ -119,6 +132,9 @@
   batched and unbatched components, an inert replay of an applied revision,
   cancellation of the request left in flight by the drop, incarnation ordering
   after a destroy and recreate, and payload delivery exactly once per revision
+- Authorized message-reference reads recheck the original operation and arguments,
+  return immutable JSON results for every delivery mode, and raise terminal errors
+  from `result` while `outcome` exposes them as data.
 - Result lookup by request ID and by idempotency key, authorized with the hook
   the original call ran and against the stored operation and arguments. An
   actor remembers the idempotency keys of its own last `retained_idempotency_keys`

data/docs/security.md

@@ -16,8 +16,8 @@ delegate to the authorized synchronous invocation path. Keep implementation
 helpers private or protected. Query, attribute, observable, and committed
 `snapshot` reads use the separate query authorization policy. Explicit `async`
 message delivery uses the same message authorization policy as direct calls.
-Recovering a timed-out result through `MessageReference#wait` reauthorizes the
-stored operation.
+Message reference status, result, outcome, and wait reads reauthorize the stored
+operation and arguments with the context supplied to that read.
 `reference.destroy` delegates to `authorize_destroy` before checking whether
 the actor exists, so denial does not reveal actor existence.
 

data/docs/transmission.md

@@ -18,6 +18,9 @@ actor does the same with `transmit.increment(amount:)`. Either ingest
 accepts either sender, so Rails-to-Rails, Rails-to-Node, Node-to-Rails,
 and browser-to-Rails replication all ride one contract.
 
+An omitted `arguments` field defaults to `{}`. Explicit `null` and arrays are
+rejected by both runtimes. Shared fixtures cover this distinction.
+
 ## The sending side
 
 ```ruby
@@ -57,7 +60,7 @@ retries with backoff and dead-letters on exhaustion, like any other effect.
 
 The drain keeps per-actor order across failures: a claimed transmit effect
 delivers every undelivered sibling for its actor up to its own mailbox
-sequence, oldest first. The receiving side dedups on `transmit:<effectId>`,
+sequence, oldest first, preserving staging order within each turn. The receiving side dedups on `transmit:<effectId>`,
 so a redelivered envelope applies once.
 
 Delivery is at-least-once by design, and the drain accepts redundant sends
@@ -84,11 +87,19 @@ SolidObjects.configure do |configuration|
 end
 ```
 
-These settings apply to every effect, not only transmits. A dead transmit
-effect has no retry API; the dashboard lists it, and recovery means
-returning its row to `pending` with a cleared `attempt_count`. Order
-survives that recovery, because the drain orders by mailbox sequence, not
-by retry time.
+These settings apply to every effect, including transmits. Retry a dead transmit
+through the authorized administration API:
+
+```ruby
+SolidObjects.dead_letters.effects.retry(effect_id, authorization_context: operator)
+```
+
+Retry resets attempts and returns the effect to pending with its stable identity,
+so the receiver still deduplicates replays. The administration policy must allow
+`retry` on `effect_dead_letters`; the action is recorded in the audit log. Use
+`SolidObjects.dead_letters.effects.redrive(authorization_context: operator)` to
+recover a scope in bounded batches. Order survives recovery because the drain
+orders by source sequence and staging order.
 
 ## Wire contract
 

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.