solid_objects 0.14.1 → 0.14.2

data/docs/architecture.md

@@ -435,6 +435,45 @@ send_to(InventoryActor.ref("sku-123")).reserve(order_id: id, quantity: 2)
 
 The source actor commit never waits for the target. The outbox worker allocates the target's sequence after source commit. There is no global order across actors.
 
+## Registering effect and commit-action handlers
+
+Register an effect handler during application boot. The stable effect ID is the
+idempotency key for the provider call:
+
+```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
+```
+
+A success callback receives `effect_id:`, the originally staged `arguments:`,
+and `result:`. A failure callback receives `effect_id:`, `arguments:`, and
+`error:`, so an actor can correlate concurrent effects without storing a
+separate callback ledger.
+
+A commit action is registered the same way and runs inside the short fenced
+transaction:
+
+```ruby
+SolidObjects.register_commit_action(:complete_attempt) do |arguments, context|
+  AssessmentAttempt.find(arguments.fetch("attempt_id")).update!(
+    score: arguments.fetch("score"),
+    actor_message_id: context.message_id
+  )
+end
+```
+
+Commit actions require Solid Objects and `ActiveRecord::Base` to share one
+connection pool, and may be invoked again after a database rollback, so keep
+them deterministic, bounded, and database-only. When Solid Objects uses a
+separate actor database, use `emit` and an idempotent effect consumer instead;
+two databases cannot share one transaction.
+
+
 ## Reminders
 
 A reminder record contains actor identity, a reminder name, target message, JSON arguments, next run time, optional interval, status, and occurrence counter.
@@ -443,7 +482,7 @@ A reminder record contains actor identity, a reminder name, target message, JSON
 schedule(at: 30.minutes.from_now).expire
 ```
 
-Reminders are keyed by `(actor, reminder name)`, enforced by a unique index on `(instance_id, name)`. `schedule` is therefore an upsert: scheduling a name that is already armed moves that alarm instead of adding another, which is what makes re-arming safe from a handler that may run more than once. An actor needing several pending items should arm one alarm for the earliest and drain everything due when it fires, rather than one alarm per item; the [reminders guide](../README.md#a-reminder-is-one-named-alarm-per-actor) shows that pattern. A move that changes `next_run_at` emits `solid_objects.reminder.replaced`, because the replacement is otherwise indistinguishable from a first schedule.
+Reminders are keyed by `(actor, reminder name)`, enforced by a unique index on `(instance_id, name)`. `schedule` is therefore an upsert: scheduling a name that is already armed moves that alarm instead of adding another, which is what makes re-arming safe from a handler that may run more than once. An actor needing several pending items should arm one alarm for the earliest and drain everything due when it fires, rather than one alarm per item; the [reminders guide](reminders.md#one-alarm-for-a-whole-queue) shows that pattern. A move that changes `next_run_at` emits `solid_objects.reminder.replaced`, because the replacement is otherwise indistinguishable from a first schedule.
 
 When due, the scheduler locks the source instance and creates a normal mailbox
 row with an idempotency key derived from reminder ID and occurrence. The

data/docs/operations.md

@@ -23,6 +23,103 @@ process, its activations, and its claimed messages untouched, including when an
 application call overlaps the probe. A database busy enough to block cleanup
 reports a failed or warned check rather than raising out of the command.
 
+## Installing and upgrading
+
+Review [CHANGELOG.md](CHANGELOG.md) for compatibility and deployment-order
+notes, then update the gem:
+
+```bash
+bundle update solid_objects
+```
+
+If the `Gemfile` pins an exact version, update that constraint first and run
+`bundle install`. Commit both `Gemfile.lock` and the copied Solid Objects
+migrations.
+
+Copy only migrations that the newer gem has added, migrate, and verify the
+installation:
+
+```bash
+bin/rails solid_objects:install:migrations
+bin/rails db:migrate
+bin/rails solid_objects:doctor
+```
+
+The migration task skips engine migrations already present in the application
+and gives new migrations host-specific timestamps. Inspect the resulting
+`db/migrate/*.solid_objects.rb` files before applying them. Do not rerun
+`generate solid_objects:install` during an upgrade because that also attempts
+to regenerate the application initializer.
+
+When Solid Objects uses a separate database configuration named `actors`, copy
+and run migrations through that database's configured migration path:
+
+```bash
+DATABASE=actors bin/rails solid_objects:install:migrations
+bin/rails db:migrate:actors
+bin/rails solid_objects:doctor
+```
+
+For production, back up the actor database and run new migrations before
+starting application or Solid Objects worker processes that require the new
+schema. Restart the web and Solid Objects worker fleet after the bundle and
+schema are current. For releases that change actor state versions, also follow
+the [state migration and rolling-deployment guide](docs/state-migrations.md);
+Rails schema migrations and actor state migrations are separate concerns.
+
+### Host application tooling
+
+Installed engine migrations are copied as
+`db/migrate/*_create_solid_objects_tables.solid_objects.rb`. If the host enables
+`Rails/CreateTableWithTimestamps`, exclude engine-owned migrations rather than
+editing their intentionally specialized hot tables:
+
+```yaml
+Rails/CreateTableWithTimestamps:
+  Exclude:
+    - "db/migrate/*.solid_objects.rb"
+```
+
+Solid Objects ships inline RBS signatures, not RBI files. Sorbet applications
+can generate the gem RBI with:
+
+```bash
+bundle exec tapioca gem solid_objects
+```
+
+### Running an extension in the same process
+
+An extension gem can register its own long-running component, and
+`solid_objects start` runs it beside the built-in roles. The component joins the
+same supervision, the same replacement after a crash, and the same shutdown
+timeout, so an operator deploys and monitors one process instead of two:
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.register_component { MyExtension::FlushEngine.new }
+end
+```
+
+Pass `count:` for more than one instance. The block runs once for each instance,
+and again when the supervisor replaces a crashed one, so no two components share
+an object.
+
+A registered component answers four methods, the contract the built-in roles
+already keep:
+
+| Method | Purpose |
+| --- | --- |
+| `run` | Runs the loop. The supervisor calls it in its own thread |
+| `request_shutdown` | Asks the loop to finish. It must make `run` return |
+| `stopped?` | Reports whether the component already finished |
+| `stop` | Forces cleanup when the shutdown timeout expires first |
+
+The supervisor checks that contract when it builds the component, and a missing
+method raises `ArgumentError` as the supervisor starts, rather than hanging a
+shutdown later. Registration itself never calls the block, so a component is
+free to need a database connection that the application does not have while it
+boots.
+
 ## Runtime
 
 Start all configured roles:
@@ -50,6 +147,16 @@ actors by name for Cable subscriptions and component renders. Loading them in
 every process is what lets a freshly booted web process serve a live card for
 an actor no request in that process has rendered yet.
 
+Worker and outbox counts can be overridden on the command line:
+
+```bash
+bundle exec solid_objects start \
+  --workers 4 \
+  --effect-workers 2 \
+  --broadcast-workers 2 \
+  --reminder-schedulers 1
+```
+
 Inspect process records and clean stale ownership:
 
 ```bash
@@ -70,26 +177,45 @@ bundle exec solid_objects retry_dead_letter 123
 
 ## Configuration
 
-Important controls include:
-
-- `worker_count`
-- `effect_worker_count`
-- `broadcast_worker_count`
-- `reminder_scheduler_count`
-- `max_messages_per_activation_pass`
-- `max_activation_duration`
-- `idle_deactivation_timeout`
-- `lease_duration`
-- `lease_renewal_interval`
-- `polling_interval`
-- `idle_polling_interval`
-- `max_mailbox_length`
-- payload, state, and result byte limits
-- retry attempts and delay
-- heartbeat interval and alive threshold
-- message retention and per-actor-type overrides
-- opt-in actor-instance retention by actor type
-- stopped-process retention and prune batch size
+Configure Solid Objects in `config/initializers/solid_objects.rb`:
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.worker_count = 4
+  configuration.lease_duration = 30.seconds
+  configuration.lease_renewal_interval = 10.seconds
+  configuration.max_messages_per_activation_pass = 50
+  configuration.max_activation_duration = 5.seconds
+end
+```
+
+| Setting | Default |
+| --- | ---: |
+| `polling_interval` | 0.1 seconds |
+| `idle_polling_interval` | 1 second |
+| `sync_polling_interval` | 0.05 seconds |
+| `lease_duration` | 30 seconds |
+| `lease_renewal_interval` | 10 seconds |
+| `idle_deactivation_timeout` | 30 seconds |
+| `max_messages_per_activation_pass` | 50 |
+| `max_activation_duration` | 5 seconds |
+| `max_mailbox_length` | 10,000 |
+| `max_attempts` | 5 |
+| `process_heartbeat_interval` | 15 seconds |
+| `process_alive_threshold` | 60 seconds |
+| `message_retention` | 30 days |
+| `message_retention_by_actor_type` | `{}` |
+| `instance_retention_by_actor_type` | `{}`; instances never expire unless listed |
+| `process_retention` | 7 days |
+| `prune_batch_size` | 1,000 |
+| `worker_count` | 1 |
+| `effect_worker_count` | 1 |
+| `broadcast_worker_count` | 1 |
+| `reminder_scheduler_count` | 1 |
+
+Payload, state, and result byte limits; retry delay; table prefix; logging;
+wake-up; broadcast; database; and authorization adapters are also configurable.
+Invalid lease intervals, component counts, and size limits fail fast at boot.
 
 Keep lease duration comfortably above renewal interval and expected database
 pause time. A handler can exceed the pass-duration budget because Ruby code is

data/docs/reminders.md

@@ -0,0 +1,112 @@
+# Reminders
+
+Reminders are Solid Objects' durable equivalent of the Durable Objects Alarms
+API. One-shot and recurring alarms are actor-owned database records:
+
+```ruby
+def schedule_evaluation
+  schedule(
+    at: 1.hour.from_now,
+    every: 1.hour,
+    missed: :latest
+  ).evaluate(account_id:)
+end
+```
+
+Use `missed: :latest` to coalesce missed occurrences or `missed: :all` to
+enqueue each one.
+
+## A reminder is one named alarm per actor
+
+The uniqueness key is `(actor, reminder name)`. Scheduling a name that is
+already armed **moves the existing alarm** rather than adding a second one. The
+database enforces this with a unique index on `(instance_id, name)`.
+
+This is the same model as Orleans reminders and Durable Objects alarms, and it
+is what makes a reminder safe to re-arm from a handler that may run more than
+once. Without a key the name is the operation, so this is a data-loss bug:
+
+```ruby
+# Wrong. Every entry overwrites the previous entry's alarm.
+def add(entry:)
+  self.entries = entries + [ entry ]
+  schedule(at: entry.fetch("wait_until")).deliver
+end
+```
+
+Two entries leave one reminder. The earlier wake-up never happens, nothing
+raises, and nothing is logged except a `solid_objects.reminder.replaced` event.
+
+## An alarm per item, with `key:`
+
+Pass `key:` when an actor is waiting on several things at once. The key is your
+own identifier for the item, and it names that item's alarm, so each item gets
+one:
+
+```ruby
+def add(entry:)
+  self.entries = entries + [ entry ]
+  schedule(at: entry.fetch("wait_until"), key: entry.fetch("id")).deliver
+end
+```
+
+Two entries now leave two reminders. Scheduling the same key again moves that
+item's alarm and leaves the others alone, which is what makes a keyed reminder
+as safe to re-arm as an unkeyed one. The operation still decides which handler
+runs; the 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.
+
+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
+one name, and the second would silently take the first one's alarm. A key may
+hold colons of its own, because the operation before the first one cannot.
+
+## One alarm for a whole queue
+
+A key per item is not always what you want. An actor that only ever needs to
+know "what is next" can keep one alarm and let the handler drain everything now
+due before arming the next:
+
+```ruby
+def add(entry:)
+  self.entries = (entries + [ entry ]).sort_by { |item| item.fetch("wait_until") }
+  arm_next
+end
+
+def deliver
+  now = Time.current.to_i
+  due, pending = entries.partition { |item| item.fetch("wait_until") <= now }
+  due.each { |item| emit :send_push, **item.symbolize_keys }
+  self.entries = pending
+  arm_next
+end
+
+private
+
+def arm_next
+  earliest = entries.first
+  return unless earliest
+
+  schedule(at: Time.at(earliest.fetch("wait_until"))).deliver
+end
+```
+
+That costs one reminder row instead of one per item, and a coalesced occurrence
+cannot strand an entry because the handler drains by time rather than by alarm.
+Prefer it when the queue is large and the items are interchangeable; prefer
+`key:` when an item needs its own alarm that can be moved on its own.
+
+Solid Objects has no `unschedule`. A reminder stops when its handler does not
+re-arm it, and destroying an actor removes its reminders.
+
+Self-scheduling actors should also have a low-frequency application reconciler.
+It may read `SolidObjects::Instance.states_for`, `.without_pending_work`, and
+`.orphaned`, but every repair must go through `async`. Never bulk-update actor
+state around the lease and fencing checks.
+
+Suspended actors should be reported rather than silently resumed. Spread large
+repair batches with `available_at:` so reconciliation cannot stampede one
+mailbox or the worker fleet.

data/lib/solid_objects/version.rb

@@ -1,5 +1,5 @@
 # rbs_inline: enabled
 
 module SolidObjects
-  VERSION = "0.14.1"
+  VERSION = "0.14.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.14.1
+  version: 0.14.2
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-24 00:00:00.000000000 Z
+date: 2026-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -355,6 +355,7 @@ files:
 - docs/migrating-existing-state.md
 - docs/operations.md
 - docs/realtime.md
+- docs/reminders.md
 - docs/research/solid_queue.md
 - docs/roadmap.md
 - docs/security.md