solid_objects 0.16.1 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b060638b79ca2236a6530f8c478fe28ac0453fc514a0daeeb5f0f3a400f446ee
-  data.tar.gz: 31424c65ecc34caab85a2296b3e2f7055f731b07a5db16022fc48d1fcc860ed6
+  metadata.gz: 3b918d2d78f5336b1eeda97b9f59560b6ef22cb4703524fd17c368c3fcb90b8d
+  data.tar.gz: 26483ce973457d40dceb52a14bb311417e476a9bd84ce8dc5f85e814a16db9af
 SHA512:
-  metadata.gz: 6fee1b678cfb18e2a0b59c1e275a079631570b7a7b44cdd9edc2e0d880ec7efc688f9ee59bc9e3afb2742f355f793939f9a263f07f9e3a7bc466c07367dcbb23
-  data.tar.gz: 5d92fe6f884c53b757c5dde1ab372afe0200a3f509ddef737f75bd8810f42e224def36ce363abf57d1e41326fe2dc5ff0985b111deed3656db960a3889b26d9c
+  metadata.gz: 0ac2d7b510bd69aad30b8b32c8330725c08e52625ceca66a0cfde34e61f316b904aa2f21705473034096560479ff94dbc8c8a072b68e0a4e852de89c182f2bcc
+  data.tar.gz: 7061098cc192a52606d2957380d8a6a6d842e8a67c2c13aad0873efcfdad691bb0783fbb5252554a896d5a2424a88d24cfb5454bdb80990c5b20a6b9c65f8847

data/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## 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
+  event observers in `sig/public/telemetry.rbs`, and a `json_value` type for
+  message results and actor state. Observer blocks, diagnostics, and results now
+  type-check against these contracts instead of `untyped`.
+- **Breaking:** `solid_objects.activation.started` now fires before the actor's
+  `activate` hook. Before, it fired after a successful hook. The new
+  `solid_objects.activation.completed` event takes that meaning, and
+  `solid_objects.activation.failed` reports a failed hook. JavaScript changes
+  the same events. Move a subscriber that reads `activation.started` as a
+  finished activation to `activation.completed`.
+- **Breaking:** Active Support payloads no longer carry `error_message`. This
+  applies to `commit_action.failed`, `activation.deactivation_failed`,
+  `supervisor.monitor_failed`, `supervisor.retention_failed`,
+  `supervisor.redrive_failed`, and `wake_up.failed`. The
+  `solid_objects.worker.error` log entry also omits it. Each keeps
+  `error_class`. Exception text can contain actor state, so JavaScript already
+  reports only the error name.
+
+- **Breaking:** rename `solid_objects.payload_broadcast_failed` to
+  `solid_objects.payload_broadcast.failed`, the dotted form that every other
+  event uses. Update Active Support subscribers to the new name. The portable
+  event names the payload `payload`.
+- Match portable event attributes to JavaScript through the shared
+  `compatibility/telemetry-events.json` contract. Message events carry
+  `operation` and `deliveryMode`, `message.failed` carries `retryable` and
+  `outcome`, commit action events carry the message fields and `commitAction`,
+  and `reminder.enqueued` carries `operation`. `outbox.age` carries the effect or
+  broadcast identity, `sync.enqueue_timeout` carries `timeoutMilliseconds`, and
+  polling intervals are integers. `realtime.connected` carries only actor fields.
+- Log `solid_objects.instrumentation.failed` when an exporter or observer raises.
+  Observers require a block, a process accepts at most 1,000 observers, and
+  `SolidObjects.reset!` removes them. Pin reserved JSON keys through actor
+  arguments, state, and retained results.
+
+- Guard personalized payload projections against state changes, staged work,
+  and application database writes. Each payload gets an isolated actor from
+  the committed snapshot and honors `max_payload_bytes`, matching JavaScript.
+- Preserve timeout wait reasons, activation owner IDs, and activation generations
+  in portable telemetry using the shared camelCase fields and reason values.
+- Use a yielding SQLite busy handler for background transactions so concurrent
+  writers can finish on Rails 7.1 and 7.2. Preserve configured wait limits and
+  synchronous deadlines; cover contention with a coordinated lock regression.
+
+- **Breaking:** reject query and observable state mutation and staged durable
+  work with terminal `QueryMutatedState` errors. Cover individual snapshot
+  projections and preserve ordinary operations' already-staged work while
+  reading projections, including replacements that leave the intent count
+  unchanged.
+- Pin reserved JSON property names with shared Ruby/JS fixtures. Document the
+  reminder-name limit difference and the authorized dead-transmit retry API.
+
+- **Breaking:** reauthorize every message-reference status, result, and outcome
+  read against the original invocation. Pass `authorization_context:` on every
+  read.
+- **Breaking:** retain immutable JSON results for background and internal
+  messages as well as synchronous calls. All operations now enforce result
+  serialization and size limits; return `nil` explicitly when an operation does
+  not need a result. `result` raises terminal rejection/failure errors;
+  `outcome` exposes them as data.
+- Preserve polling transition intervals in milliseconds and string reasons in
+  portable telemetry. Pin transmit staging order and null-argument validation
+  against the shared JavaScript contract.
+
+- Add portable telemetry, isolated observer hooks, metric definitions, and bounded authorized actor diagnostics matching JavaScript.
+
 ## 0.16.1 - 2026-10-02
 
 - Fix the SQLite join order of the claimed-message scan. The query in

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.
@@ -160,8 +166,11 @@ 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)
 - [Reminders](docs/reminders.md)
 - [Reactive ERB](docs/realtime.md)
 - [Detailed architecture](docs/architecture.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/app/models/solid_objects/message.rb

@@ -47,6 +47,21 @@ module SolidObjects
       dead_letter.present?
     end
 
+    # @rbs () -> json_value
+    def result!
+      if rejected?
+        raise Rejected.new(
+          code: rejection.fetch("code"),
+          message: rejection.fetch("message"),
+          details: rejection.fetch("details"),
+          message_id: id
+        )
+      end
+      raise MessageFailed.new("actor message failed permanently", message_id: id, details: error || {}) if dead?
+
+      Serialization.readonly_copy(result)
+    end
+
     private
 
     # @rbs () -> void

data/docs/agents.md

@@ -0,0 +1,253 @@
+# 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.
+
+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.
+- 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`, 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/architecture.md

@@ -167,10 +167,12 @@ creating a message or activation, applies required state migrations in memory,
 and returns deeply frozen declared attributes. It can race with an in-flight
 turn. `SolidObjects.mutable_copy` creates an independent mutable JSON value.
 
-`message` and `query` both execute as durable mailbox turns. A query may not
-mutate state. The executor detects query mutation and fails the message. An
-observable is a named projection of state used by server rendering and realtime
-updates. Its durable broadcast row stores only an empty invalidation marker by
+`message` and `query` both execute as durable mailbox turns. Queries and
+observables must not mutate state or stage effects, recovery checks, commit
+actions, reminders, or outbound messages. Violations raise `QueryMutatedState`
+and fail the message without retrying or committing its work. Individual snapshot
+projections enforce the same rule. An observable is a named projection used by
+server rendering and realtime updates. Its durable broadcast row stores only an empty invalidation marker by
 default. `broadcast: :value` explicitly opts into storing and sharing the
 projected value.
 
@@ -431,8 +433,16 @@ Each lookup runs the authorization hook the original call ran, against the
 stored operation and arguments, and answers `nil` for an absent row, an
 unregistered actor, and a refused caller alike, so it cannot be used to ask
 whether a request id exists. `MessageReference#outcome` reports the status, the
-result, the persisted error, the rejection, and the attempt count. A result is
-stored for `sync` delivery only.
+result, the persisted error, the rejection, and the attempt count. Every delivery
+mode stores its JSON result, including background messages. Result serialization
+and `max_result_bytes` apply before commit; a result that cannot be stored fails
+the turn. Return `nil` explicitly from operations that need no result.
+
+`status`, `result`, and `outcome` reauthorize the stored operation on every read.
+Pass `authorization_context:` each time; references retain identity rather than
+caller permissions. `result` raises `Rejected` or `MessageFailed` for terminal
+errors and returns a deeply frozen successful value. `outcome` reports terminal
+errors as data.
 
 An actor remembers the idempotency keys of its own finished turns. The executor
 already writes the instance row in the transaction that completes, rejects, or

data/docs/authorization.md

@@ -13,13 +13,20 @@ answers nothing until the host application defines its trust boundary.
 | `authorize_query` | Attribute reads, declared queries, committed snapshots, scalar observable reads, initial component rendering, and every component refresh dependency | Explicit call context, the context passed to `solid_object`, or the request context resolved for a component refresh | Actor state or personalized projections can leak across users or tenants |
 | `authorize_destroy` | `reference.destroy` | Value passed as `authorization_context:` | Complete actor state, mailbox, reminders, and pending outboxes can be deleted |
 | `authorize_subscription` | Action Cable subscription to one actor stream | The `ActionCable::Connection` object | Clients can receive future observable updates for other actors |
-| `authorize_administration` | Engine administration controllers, every `SolidObjects::Web` page, process inspection/cleanup/pruning, message pruning, and dead-letter inspection/retry | Rails controller, a `SolidObjects::Web` request that answers `request`/`session`/`env`, or `{ source: "cli" }` | Operational metadata, arguments, errors, deletion, and retries become exposed or mutable |
+| `authorize_administration` | Engine administration controllers, every `SolidObjects::Web` page, process inspection/cleanup/pruning, message pruning, dead-letter inspection/retry, and actor diagnostics and observers | Rails controller, a `SolidObjects::Web` request that answers `request`/`session`/`env`, or `{ source: "cli" }` | Operational metadata, arguments, errors, deletion, and retries become exposed or mutable |
 
-Waiting again through `MessageReference#wait` reauthorizes the stored
-invocation as a message or query. Internal reminder, effect-callback, and
+Every `MessageReference#status`, `#result`, `#outcome`, and `#wait` call
+reauthorizes the stored operation and arguments as a message or query. Supply
+`authorization_context:` on each call, including after `find_by`; the reference
+does not retain the original caller's context. Internal reminder, effect-callback, and
 actor-to-actor deliveries come from
 already committed runtime rows and do not re-enter the public client policy.
 
+Actor diagnostics and actor observers call `authorize_administration` with the
+resource `actor_diagnostics` and the resource ID `[actor_type, actor_id].to_json`.
+`diagnostics` uses the action `:inspect`. `observe` and `on` use the action
+`:observe`. The check runs before any queue read or observer registration.
+
 ## Realtime authorization contexts
 
 Reactive components cross three Rails execution contexts and authorize at all