solid_objects 0.11.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 530d40a11cbf715cc3657191124d336798d4e8efdccb129d8ee0431400ec36ff
-  data.tar.gz: 39abe950312fa41ab57aa55e7e01a088a01eb63dcfd535e0ada712ae75c03b01
+  metadata.gz: 7e89f40dd095ec1d8934ff47872f3638ca441203186a7a1562dc9f603c939150
+  data.tar.gz: 23389e8737fcbfc816ca41aedf56f4b83baa6769fc2c54f6d9ca3622c67ca135
 SHA512:
-  metadata.gz: edd288ba3cc57f8ac7c241eda9e3e320385f26071a5dc1e11e3676af1106dc1ddadddfa520ff08f4ce61a0b2f73c23d1a2418199c8f6f98ebe85fe2b51b07426
-  data.tar.gz: 38e5561275048f00dcbd5e363b0d3da6a00242348094776c63da44df7e2ca694292e7bc0546d44ac5da7a8883eb70d3e237d7495c888d6d3e2dd9d286d1754f0
+  metadata.gz: d28e8e826c045dc546a13eb34631c692281b82b10a55205f0f6b3a17b77a1a2144bbfb786c69c86d701d42d356c65da4c26d7dd2f25a5538f9743e4405aa53b1
+  data.tar.gz: 34c89447e1592ea056d511db1fbf01de898c1563c34616a7b80058b0c1bb649b3a4e01cf7f1fad6de35bedc82e484c0a8c96b21aa0be1d959b94c3492fd3d3c4

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.12.1 - 2026-08-13
+
+- Add invalidation-only observables with `broadcast: :invalidation`. They still
+  detect changes and refresh reactive components, but persist `{}` and send no
+  scalar value over Action Cable. Document that ordinary observable values are
+  shared with every authorized actor subscriber and that subscriber-specific
+  state belongs in a payload projection.
+- **Breaking:** include the originally staged `arguments:` in effect success
+  and failure callbacks so actors can correlate concurrent effects.
+- Accept identifier-style rejection codes, including camelCase and symbols,
+  and fail malformed codes once with non-retryable
+  `SolidObjects::InvalidRejectionCode` diagnostics.
+- Add `run_due_reminders(now:)` to `SolidObjects::TestHelper` for deterministic
+  reminder tests without sleeping or mutating runtime rows.
+
+## 0.12.0 - 2026-08-13
+
+- Replace positional actor dispatch with fluent operation selection. Direct
+  committed calls remain `account.disable(...)`; configured committed calls
+  use `account.sync(timeout: ...).status`; asynchronous calls use
+  `account.async(...).disable(...)`; actor outbox delivery uses
+  `send_to(account, ...).disable(...)`; and reminders use
+  `schedule(at: ...).evaluate(...)`. Delivery and reminder options are now
+  unambiguously separate from actor message arguments. The former positional
+  `async`, `sync`, `send_to`, and `schedule` forms are removed.
+- Validate fluent operations before enqueueing or staging them. Direct and
+  configured synchronous calls accept messages and queries, while `async`,
+  `send_to`, and `schedule` accept public actor messages only.
+- Use operation terminology throughout invocation persistence and diagnostics.
+  The new migration renames stored message names to `operation`, message kind
+  to `delivery_mode`, and effect callback message names to operation names.
+- Make internal methods with more than two arguments keyword-only so dispatch,
+  persistence, component refresh, and diagnostics call sites name every value.
+- Keep SQLite reconnect failures inside a synchronous lock deadline. Active
+  Record can reconnect after a lock error while the lock is still held, and
+  configuring WAL then raises `SQLite3::CantOpenException`; it now retries
+  within the original deadline and surfaces the documented sync timeout.
+
 ## 0.11.0 - 2026-08-11
 
 - Add `SolidObjects.configuration.register_component`. An extension gem can now

data/README.md

@@ -27,7 +27,7 @@ current_count = counter.value
 current_snapshot = counter.snapshot.value
 
 # Durable fire-and-forget delivery. A worker processes it later.
-message = counter.async(:increment, amount: 5)
+message = counter.async.increment(amount: 5)
 ```
 
 `Counter / global` is a logical identity. Like a Durable Object named with
@@ -41,10 +41,10 @@ The invocation model is the first adoption decision:
 | Call | Returns | Worker fleet required? |
 | --- | --- | --- |
 | `counter.increment(amount: 5)` | Committed handler result | No |
-| `counter.sync(:increment, amount: 5)` | Committed handler result | No |
+| `counter.sync(timeout: 5.seconds).increment(amount: 5)` | Committed handler result | No |
 | `counter.value` | Ordered, committed query result | No |
 | `counter.snapshot.value` | Current committed state without a mailbox message | No |
-| `counter.async(:increment, amount: 5)` | `MessageReference` immediately | Yes |
+| `counter.async.increment(amount: 5)` | `MessageReference` immediately | Yes |
 
 Direct methods and `sync` durably enqueue the call, then the Rails caller helps
 execute the actor through the same mailbox, lease, and fencing path as a
@@ -155,7 +155,7 @@ durable reminders owned by one logical identity:
 
 ```ruby
 def schedule_expiration
-  schedule :expire, at: 30.minutes.from_now, arguments: {}
+  schedule(at: 30.minutes.from_now).expire
 end
 ```
 
@@ -205,6 +205,21 @@ dependencies changes:
 <% end %>
 ```
 
+An observable's value is shared with every authorized subscriber by default
+and is stored in `solid_objects_broadcasts`. Use an invalidation-only observable
+for component dependencies whose value is private or subscriber-specific:
+
+```ruby
+observable :player_one, broadcast: :invalidation do
+  player_in_seat(1)
+end
+```
+
+Its value is still available to the authorized component renderer, but the
+durable row and Action Cable frame carry only invalidation metadata. It cannot
+be rendered as a scalar `<span>`. Put per-viewer state in `broadcast_payload`,
+which computes a fresh projection for each connection.
+
 Component names can repeat when each instance has a stable key. Signed
 JSON-compatible locals let one conventional partial render the matching
 projection:
@@ -536,7 +551,7 @@ cart.add_item(product_id: "shirt-123", quantity: 2)
 items = cart.items
 ```
 
-Use `cart.async(:add_item, product_id: "shirt-123", quantity: 2)` to enqueue
+Use `cart.async.add_item(product_id: "shirt-123", quantity: 2)` to enqueue
 without waiting; that call returns a `SolidObjects::MessageReference`. `items`
 is a deeply frozen JSON snapshot, so mutating it cannot bypass the actor
 mailbox. State changes must go through public actor methods or explicit
@@ -638,26 +653,34 @@ Use `async` for durable fire-and-forget work. It returns a
 
 ```ruby
 message = order.async(
-  :submit,
-  idempotency_key: "submit-order-123"
-)
+  idempotency_key: "submit-order-123",
+  authorization_context: Current.user
+).submit
 ```
 
 Use `available_at:` to spread bulk work or delay one message:
 
 ```ruby
-order.async(:evaluate, available_at: 10.minutes.from_now)
+order.async(available_at: 10.minutes.from_now).evaluate
 ```
 
 ### `sync`
 
-Use explicit `sync` when the operation name is dynamic or collides with a
-reference method:
+Use explicit `sync` when the invocation needs a timeout, idempotency key, or
+authorization context different from the defaults:
 
 ```ruby
-status = order.sync(:status, timeout: 5.seconds)
+status = order.sync(
+  timeout: 5.seconds,
+  authorization_context: Current.user
+).status
 ```
 
+Delivery configuration belongs on `async(...)` or `sync(...)` before the
+operation. Keywords on the final method call are always actor message
+arguments, so `order.sync(timeout: 5.seconds).record(timeout: "payload")`
+keeps the invocation timeout separate from the payload value.
+
 Direct calls and `sync` use the same caller-assisted execution path. A healthy
 actor normally needs no worker round trip, making this path suitable for HTTP
 and MCP request/response boundaries when the handler itself fits the
@@ -677,7 +700,7 @@ recover its eventual result through the durable message identity:
 
 ```ruby
 begin
-  order.submit(timeout: 250.milliseconds)
+  order.sync(timeout: 250.milliseconds).submit
 rescue SolidObjects::SyncTimeout => error
   result = error.message_reference.wait(
     timeout: 5.seconds,
@@ -700,6 +723,17 @@ Actor code cannot use direct calls or `sync` on another actor; synchronous
 actor-to-actor waits can deadlock in cycles. Use `async` or `send_to` and a
 result message.
 
+```ruby
+send_to(
+  audit_log,
+  available_at: 5.minutes.from_now,
+  idempotency_key: event_id
+).record(event_id:, event_name: "account_disabled")
+```
+
+Actor-to-actor delivery is staged with the current turn, returns `nil`, and is
+discarded if that turn does not commit. It accepts messages, not queries.
+
 ### Domain rejection
 
 Reject invalid input without retrying or creating a dead letter:
@@ -717,8 +751,8 @@ JSON-compatible details. The rejected message remains durable for audit, actor
 state is rolled back, and no later mailbox turn is blocked.
 
 `Rejected#code` is a `String`, even when `reject` receives a symbol. Codes must
-match `\A[a-z][a-z0-9_]*\z`; invalid codes raise `ArgumentError` when the
-handler calls `reject`.
+match `\A[A-Za-z_][A-Za-z0-9_]*\z`. Invalid codes raise
+`SolidObjects::InvalidRejectionCode` and fail the turn without retrying.
 
 ### Redelivery
 
@@ -800,11 +834,11 @@ def checkout(payment_id:, amount_cents:)
   )
 end
 
-def payment_succeeded(effect_id:, result:)
+def payment_succeeded(effect_id:, arguments:, result:)
   self.checkout_status = "paid"
 end
 
-def payment_failed(effect_id:, error:)
+def payment_failed(effect_id:, arguments:, error:)
   self.checkout_status = "failed"
 end
 ```
@@ -823,6 +857,10 @@ end
 
 The provider call can repeat if a process dies after external success but
 before recording completion. The stable effect ID is the idempotency key.
+Success callbacks receive `effect_id:`, the originally staged `arguments:`,
+and `result:`. Failure callbacks receive `effect_id:`, `arguments:`, and
+`error:`, so an actor can correlate concurrent effects without storing a
+separate callback ledger.
 
 ## Reminders
 
@@ -831,7 +869,11 @@ API. One-shot and recurring alarms are actor-owned database records:
 
 ```ruby
 def schedule_evaluation
-  schedule :evaluate, at: 1.hour.from_now, every: 1.hour, missed: :latest
+  schedule(
+    at: 1.hour.from_now,
+    every: 1.hour,
+    missed: :latest
+  ).evaluate(account_id:)
 end
 ```
 
@@ -852,7 +894,7 @@ once. It also means this is a data-loss bug:
 # Wrong. Every entry overwrites the previous entry's alarm.
 def add(entry:)
   self.entries = entries + [ entry ]
-  schedule :deliver, at: entry.fetch("wait_until"), arguments: {}
+  schedule(at: entry.fetch("wait_until")).deliver
 end
 ```
 
@@ -882,7 +924,7 @@ def arm_next
   earliest = entries.first
   return unless earliest
 
-  schedule :deliver, at: Time.at(earliest.fetch("wait_until")), arguments: {}
+  schedule(at: Time.at(earliest.fetch("wait_until"))).deliver
 end
 ```
 

data/app/controllers/solid_objects/components_controller.rb

@@ -55,7 +55,7 @@ module SolidObjects
           "target" => registration.dom_id,
           "revision" => "#{snapshot.instance_id}:#{snapshot.revision}",
           "refresh_method" => registration.refresh_method,
-          "html" => component_frame(registration, snapshot, rendered)
+          "html" => component_frame(registration:, snapshot:, rendered:)
         }
       end
       response.headers["Cache-Control"] = "private, no-store"
@@ -118,7 +118,7 @@ module SolidObjects
       ).call
       response.headers["Cache-Control"] = "private, no-store"
       payload[:outcome] = "rendered"
-      render html: component_frame(registration, snapshot, rendered)
+      render html: component_frame(registration:, snapshot:, rendered:)
     rescue Unauthorized
       payload[:outcome] = "unauthorized"
       head :forbidden
@@ -182,8 +182,8 @@ module SolidObjects
       end
     end
 
-    # @rbs (ComponentRegistration, ActorSnapshot, untyped) -> String
-    def component_frame(registration, snapshot, rendered)
+    # @rbs (registration: ComponentRegistration, snapshot: ActorSnapshot, rendered: untyped) -> String
+    def component_frame(registration:, snapshot:, rendered:)
       revision = "#{snapshot.instance_id}:#{snapshot.revision}"
       %(<turbo-frame id="#{registration.dom_id}" data-solid-objects-revision="#{revision}" data-solid-objects-refresh="#{registration.refresh_method}">#{rendered}</turbo-frame>).html_safe
     end

data/app/models/solid_objects/broadcast.rb

@@ -6,5 +6,13 @@ module SolidObjects
 
     belongs_to :message, class_name: "SolidObjects::Message"
     belongs_to :instance, class_name: "SolidObjects::Instance"
+
+    # @rbs () -> bool
+    def broadcasts_value?
+      return false if observable_name == PayloadBroadcast::REVISION_OBSERVABLE
+
+      actor_class = SolidObjects.registry.fetch(instance.actor_type)
+      actor_class.definition.broadcasts_observable_value?(observable_name)
+    end
   end
 end

data/app/models/solid_objects/message.rb

@@ -20,7 +20,7 @@ module SolidObjects
 
     before_validation :supply_defaults
 
-    validates :message_kind, inclusion: { in: %w[async sync internal] }
+    validates :delivery_mode, inclusion: { in: %w[async sync internal] }
 
     # @rbs () -> bool
     def ready?

data/app/views/solid_objects/dead_letters/index.html.erb

@@ -15,7 +15,7 @@
     <% @dead_letters.each do |dead_letter| %>
       <tr>
         <td><%= dead_letter.actor_type %>(<%= dead_letter.actor_id %>)</td>
-        <td><%= dead_letter.message_name %></td>
+        <td><%= dead_letter.operation %></td>
         <td><%= dead_letter.attempts %></td>
         <td><%= dead_letter.exception_class %>: <%= dead_letter.exception_message %></td>
         <td><%= dead_letter.last_failed_at %></td>

data/app/views/solid_objects/instances/show.html.erb

@@ -26,7 +26,7 @@
     <% @messages.each do |message| %>
       <tr>
         <td><%= message.sequence %></td>
-        <td><%= message.message_name %></td>
+        <td><%= message.operation %></td>
         <td><%= message.attempt_count %></td>
         <td><%= message.completed_at %></td>
       </tr>

data/benchmark/support.rb

@@ -98,13 +98,13 @@ module SolidObjectsBenchmark
     def enqueue
       reference = CounterActor.ref("enqueue")
       measure("enqueue #{count} messages") do
-        count.times { reference.async(:increment) }
+        count.times { reference.async.increment }
       end
     end
 
     # @rbs () -> void
     def claim
-      count.times { |index| CounterActor.ref("claim-#{index}").async(:increment) }
+      count.times { |index| CounterActor.ref("claim-#{index}").async.increment }
       process_registry = SolidObjects::ProcessRegistry.new
       owner_id = process_registry.register.id
       activation_manager = SolidObjects::ActivationManager.new(owner_id:)
@@ -137,7 +137,7 @@ module SolidObjectsBenchmark
 
     # @rbs () -> void
     def cold_actors
-      count.times { |index| CounterActor.ref("cold-#{index}").async(:increment) }
+      count.times { |index| CounterActor.ref("cold-#{index}").async.increment }
       worker = SolidObjects::Worker.new
       measure("process #{count} cold actors") { drain(worker) }
     ensure
@@ -147,7 +147,7 @@ module SolidObjectsBenchmark
     # @rbs () -> void
     def hot_actor
       reference = CounterActor.ref("hot")
-      count.times { reference.async(:increment) }
+      count.times { reference.async.increment }
       worker = SolidObjects::Worker.new
       measure("process #{count} messages for one hot actor") { drain(worker) }
     ensure
@@ -172,7 +172,7 @@ module SolidObjectsBenchmark
 
       count.times do |index|
         started_at = monotonic_now
-        CounterActor.ref("sync-#{index}").sync(:count, timeout: 5)
+        CounterActor.ref("sync-#{index}").sync(timeout: 5).count
         samples << monotonic_now - started_at
       end
 
@@ -211,7 +211,7 @@ module SolidObjectsBenchmark
     # @rbs () -> void
     def activation_cache
       reference = CounterActor.ref("cache")
-      count.times { reference.async(:increment) }
+      count.times { reference.async.increment }
       activations = 0
       subscriber = ActiveSupport::Notifications.subscribe("solid_objects.activation.started") do
         activations += 1
@@ -303,7 +303,7 @@ module SolidObjectsBenchmark
     # Runs the turn on the measuring thread, so nothing else can contribute.
     # @rbs () -> Integer
     def message_turn_query_count
-      CounterActor.ref("queries").async(:increment)
+      CounterActor.ref("queries").async.increment
       worker = SolidObjects::Worker.new
       count_queries { worker.run_once }
     ensure
@@ -322,8 +322,8 @@ module SolidObjectsBenchmark
       reference = CounterActor.ref("sync-queries")
       worker = SolidObjects::Worker.new
       runner = Thread.new { worker.run }
-      reference.sync(:increment)
-      count_queries { reference.sync(:increment) }
+      reference.sync.increment
+      count_queries { reference.sync.increment }
     ensure
       worker&.request_shutdown
       runner&.join(5)
@@ -428,7 +428,7 @@ module SolidObjectsBenchmark
     def enqueue_round_robin
       actor_count = [ concurrency * 10, count ].min
       references = Array.new(actor_count) { |index| CounterActor.ref("actor-#{index}") }
-      count.times { |index| references[index % actor_count].async(:increment) }
+      count.times { |index| references[index % actor_count].async.increment }
     end
 
     # @rbs (SolidObjects::Worker) -> Integer

data/db/migrate/20260813000000_rename_message_dispatch_columns.rb

@@ -0,0 +1,53 @@
+# rbs_inline: enabled
+
+class RenameMessageDispatchColumns < ActiveRecord::Migration[8.0]
+  # @rbs () -> void
+  def up
+    remove_check_constraint messages_table, name: "chk_so_messages_kind"
+    rename_column messages_table, :message_name, :operation
+    rename_column messages_table, :message_kind, :delivery_mode
+    rename_column reminders_table, :message_name, :operation
+    rename_column effects_table, :success_message_name, :success_operation
+    rename_column effects_table, :failure_message_name, :failure_operation
+    rename_column dead_letters_table, :message_name, :operation
+    add_check_constraint messages_table,
+      "delivery_mode IN ('async', 'sync', 'internal')",
+      name: "chk_so_messages_delivery_mode"
+  end
+
+  # @rbs () -> void
+  def down
+    remove_check_constraint messages_table, name: "chk_so_messages_delivery_mode"
+    rename_column messages_table, :operation, :message_name
+    rename_column messages_table, :delivery_mode, :message_kind
+    rename_column reminders_table, :operation, :message_name
+    rename_column effects_table, :success_operation, :success_message_name
+    rename_column effects_table, :failure_operation, :failure_message_name
+    rename_column dead_letters_table, :operation, :message_name
+    add_check_constraint messages_table,
+      "message_kind IN ('async', 'sync', 'internal')",
+      name: "chk_so_messages_kind"
+  end
+
+  private
+
+  # @rbs () -> String
+  def messages_table
+    SolidObjects.table_name(:messages)
+  end
+
+  # @rbs () -> String
+  def reminders_table
+    SolidObjects.table_name(:reminders)
+  end
+
+  # @rbs () -> String
+  def effects_table
+    SolidObjects.table_name(:effects)
+  end
+
+  # @rbs () -> String
+  def dead_letters_table
+    SolidObjects.table_name(:dead_letters)
+  end
+end

data/docs/architecture.md

@@ -63,14 +63,15 @@ The registry maps a stable persisted actor type string to a Ruby actor class. Re
 A reference contains actor type and normalized actor ID. It is cheap,
 serializable as data, and does not imply an active Ruby object. Declared
 message, query, and attribute methods use synchronous caller-assisted
-invocation. `sync` provides the same behavior for a dynamic operation name,
-while `async` only durably enqueues a message and returns its reference.
+invocation. `sync(...)` configures a caller-assisted invocation before its
+operation is selected, while `async(...)` configures durable enqueue and
+returns its message reference after the operation is selected.
 `destroy` is a reserved synchronous reference operation. Every path authorizes
 through the client.
 
 ### Client and mailbox
 
-The client finds or creates the actor instance and atomically allocates a sequence. It inserts one durable message-history row and one ready-membership row. It validates message names and JSON payloads before writing and enforces idempotency-key uniqueness, payload limits, and the per-actor mailbox cap. It also authorizes and coordinates actor destruction. Distributed rate limiting and global admission control are not implemented.
+The client finds or creates the actor instance and atomically allocates a sequence. It inserts one durable message-history row and one ready-membership row. It validates operations and JSON payloads before writing and enforces idempotency-key uniqueness, payload limits, and the per-actor mailbox cap. It also authorizes and coordinates actor destruction. Distributed rate limiting and global admission control are not implemented.
 
 Message execution state is table membership, not a status column. The durable message remains for results, retention, and diagnostics. Only live work occupies `ready_messages` or `claimed_messages`, so completed history cannot inflate the polling index.
 
@@ -112,7 +113,7 @@ The supervisor starts configured worker, effect, reminder, and broadcast thread
 
 ### Effect worker
 
-An effect worker claims due effect rows through the database coordination adapter, invokes a registered handler outside a database transaction, then records success or retryable failure. The handler receives the effect UUID as its idempotency key. Optional outcome messages are normal actor mailbox messages.
+An effect worker claims due effect rows through the database coordination adapter, invokes a registered handler outside a database transaction, then records success or retryable failure. The handler receives the effect UUID as its idempotency key. Optional outcome messages are normal actor mailbox messages and receive the effect ID, originally staged arguments, and result or error.
 
 ### Reminder scheduler
 
@@ -155,8 +156,9 @@ Public instance methods declared on the actor are messages. Declare helpers as
 private or protected. Messages and queries are exposed as methods on a
 reference through the same synchronous caller-assisted path. Returned state
 snapshots are deeply frozen. Use `async` for durable fire-and-forget delivery
-and `sync` for dynamic operation names. The explicit `message` DSL remains
-available for dynamic definitions.
+and configured `sync` when a committed call needs a non-default timeout,
+idempotency key, or authorization context. The explicit `message` DSL remains
+available for declarations defined dynamically.
 
 `reference.snapshot` is the explicit unordered read path. It invokes query
 authorization, reads the most recently committed instance state without
@@ -167,7 +169,8 @@ 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; it is not independently persisted.
+updates. Its durable broadcast row stores the projected value by default;
+`broadcast: :invalidation` stores only an empty invalidation marker.
 
 Lifecycle hooks are deterministic local hooks:
 
@@ -183,7 +186,7 @@ with application Active Record writes prevented.
 Enqueue uses one transaction:
 
 1. Resolve actor class from the registry.
-2. Validate authorization, message name, actor ID, arguments, and size.
+2. Validate authorization, operation, actor ID, arguments, and size.
 3. `INSERT ... ON CONFLICT` the actor instance if missing.
 4. Lock the instance row.
 5. Enforce the mailbox limit.
@@ -426,7 +429,7 @@ An effect handler receives JSON arguments plus an effect context. Outcome messag
 Actor code sends to another actor through a staged outbox:
 
 ```ruby
-send_to InventoryActor.ref("sku-123"), :reserve, order_id: id, quantity: 2
+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.
@@ -436,7 +439,7 @@ The source actor commit never waits for the target. The outbox worker allocates
 A reminder record contains actor identity, a reminder name, target message, JSON arguments, next run time, optional interval, status, and occurrence counter.
 
 ```ruby
-schedule :expire, at: 30.minutes.from_now, arguments: {}
+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.
@@ -467,7 +470,7 @@ The expected drift categories are actors with a lost alarm, missing actors for l
 
 Bulk repair updates to `solid_objects_instances` are forbidden. They bypass activation ownership and fencing and can overwrite a concurrently committed actor state. Direct reads are observational; writes go through actor messages.
 
-Large repairs use `async(..., available_at:)` to spread work over an application-defined dispatch window. The durable message records the requested availability and ready membership drives the hot polling query. This prevents reconciliation from flooding mailboxes and starving normal traffic.
+Large repairs use `async(available_at: ...).repair(...)` to spread work over an application-defined dispatch window. The durable message records the requested availability and ready membership drives the hot polling query. This prevents reconciliation from flooding mailboxes and starving normal traffic.
 
 ## Realtime integration
 

data/docs/authorization.md

@@ -64,7 +64,7 @@ retain an empty arguments hash. This lets a policy authorize a projection such
 as one seat or player:
 
 ```ruby
-configuration.authorize_query = lambda do |actor_type:, actor_id:, message_name:, arguments:, authorization_context:|
+configuration.authorize_query = lambda do |actor_type:, actor_id:, operation:, arguments:, authorization_context:|
   user = authorization_context
   player_id = arguments["player_id"]
 
@@ -126,7 +126,7 @@ SolidObjects.configure do |configuration|
 end
 ```
 
-The policy receives normalized actor type and ID strings, message name and
+The policy receives normalized actor type and ID strings, operation and
 arguments where relevant, and the context supplied by the caller. Avoid
 authorizing from arguments alone; bind the actor identity to the authenticated
 principal and tenant.

data/docs/database-schema.md

@@ -37,9 +37,9 @@ scheduled reminder, unresolved outbox, or dead letter before deletion.
 
 ### `messages`
 
-Durable immutable invocation identity and arguments plus sequence, attempt
-count, request/idempotency IDs, result/error, requested availability, and
-execution timestamps. A terminal domain rejection stores a structured
+Durable immutable invocation identity, selected operation, delivery mode, and
+arguments plus sequence, attempt count, request/idempotency IDs, result/error,
+requested availability, and execution timestamps. A terminal domain rejection stores a structured
 code/message/details document and rejection time. The table intentionally has
 no status column.
 
@@ -85,15 +85,15 @@ limit recurrence intervals, missed-work policies, and statuses.
 ### `effects`
 
 Transactional external-effect outbox. It stores stable effect UUID, arguments,
-optional actor outcome messages, attempts, claim ownership, result/error, and
+optional actor outcome operations, attempts, claim ownership, result/error, and
 completion time. Claim ownership references the process registry.
 Status/availability/ID drives delivery; completion/ID drives cleanup.
 
 ### `broadcasts`
 
 Durable observable-change outbox. The unique message/observable key prevents
-duplicate rows for one actor turn. Rows contain the observable JSON value and
-message/instance references used to derive invalidation metadata, never
+duplicate rows for one actor turn. Rows contain the observable JSON value, or
+`{}` for an invalidation-only observable, plus message/instance references used to derive invalidation metadata, never
 personalized rendered HTML. Claim and delivery indexes support retries and
 cleanup.
 

data/docs/development.md

@@ -56,7 +56,7 @@ Use `drain_solid_objects` to process actor, reminder, effect, callback, and
 broadcast work to a deterministic fixed point without arbitrary sleeps:
 
 ```ruby
-message = Counter.ref("test").async(:increment)
+message = Counter.ref("test").async.increment
 
 assert_equal 1, drain_solid_objects
 assert_equal "completed", message.status
@@ -65,6 +65,18 @@ assert_equal "completed", message.status
 Pass `roles: [:actors]` when a test intentionally wants to leave outboxes or
 reminders pending.
 
+Rails time travel does not move the database clock used by reminder claims. Run
+future reminders against an explicit test instant instead of updating runtime
+rows or sleeping:
+
+```ruby
+assert_equal 1, run_due_reminders(now: 5.minutes.from_now)
+assert_equal 1, drain_solid_objects(roles: [ :actors ])
+```
+
+The explicit instant controls due selection and recurring schedule advancement.
+Claim timestamps and stale-process recovery still use database time.
+
 `SolidObjects::TestHelper.reset_actors!` is also available for explicit suite
 boundaries. It deletes every actor-owned row itself rather than deleting actor
 instances and letting the database cascade remove the rest: SQLite has to be

data/docs/migrating-existing-state.md

@@ -71,11 +71,9 @@ Give every bootstrap call an idempotency key derived from the legacy record:
 
 ```ruby
 session.actor.async(
-  :bootstrap,
-  answers: legacy.answers,
   idempotency_key: "legacy-assessment:#{legacy.id}",
   available_at: jittered_time
-)
+).bootstrap(answers: legacy.answers)
 ```
 
 Spread large backfills over a dispatch window and monitor mailbox age,