solid_objects 0.10.3 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36d165ff933a151ee0cc9fbff1ae834333f9591d1ae71068a0127d198dc4d5d8
-  data.tar.gz: 1cfd279335dcf34f4cd2dd659412e04c5ac8d6ed98e1815cbd184bb38f67585f
+  metadata.gz: 15ee987ca3dcf3419f28902e2a0c18c8444c834964b743f3e7b99cd5f6dcde33
+  data.tar.gz: 45bf4d0449184c9fbf3718ce088f8541b68049e9458ee8802947fd74bef1fadb
 SHA512:
-  metadata.gz: 9328e60fa9f4e08f17cfe4404fe117af3a2c8efef53ba379b5c824d73a71063ae7f3b8e438b177ec4fcacb1ca31fdb86686212a6ac6d0f972e4f337233d6dea2
-  data.tar.gz: b39f02c65284721d06c02eee9bbd678eb808770136847715f83525e3e43fe461f89e9837c0811c6730b50584b4c74c572dcf8e3de1cbbdae7fcfbf2dbc7f6708
+  metadata.gz: 6b5b29a7f3052c1a04a012f348a9f8f1054500056073b34c8b2a6680f7d84db195efbe0d5d68809b33ba7bed04af1c141777a27801e6049df0863311cd948a25
+  data.tar.gz: 93e7bdeb0ee3a1a0c4f212f5da40c25d61bca88b1ea2dc87efb4b09d199068b5374452beb991baec05b573ac3e0109ca86dde37463a7cf5f28d823f02969767a

data/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 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
+  register a long running component, and the supervisor runs it beside the
+  workers, the effect executors, the broadcast executors, and the reminder
+  schedulers. The component joins the same supervision, replacement, and
+  shutdown timeout. Without it, an extension has to ask an operator to run and
+  monitor a second process for work that belongs to the same runtime. A
+  registered component must answer `run`, `request_shutdown`, `stopped?`, and
+  `stop`. The supervisor checks that contract when it builds the component and
+  raises `ArgumentError` when a method is missing. Registration never calls the
+  block, so a component may need a database connection that the application
+  does not have while it boots.
+
+- Stop the components already built when a later one fails. The supervisor
+  builds its components one after another, so a factory that raised, or a
+  component that failed the contract check, left the earlier ones constructed
+  and unreachable while they still held whatever their constructors took. Each
+  one now receives `stop`, and a failure inside that cleanup never replaces the
+  failure that caused it.
+
+- Replace a crashed component through the builder that made it. The supervisor
+  called `component.class.new`, which discards every constructor argument, so a
+  component built with arguments returned with its defaults after a crash. Each
+  component now keeps its builder. The built in components take no constructor
+  arguments, so their behavior does not change.
+
 ## 0.10.3 - 2026-08-11
 
 - Delete every actor-owned row in `SolidObjects::TestHelper#reset_actors!`. It

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
 ```
 
@@ -458,6 +458,39 @@ Deploy and monitor that process before enabling any feature marked as requiring
 a runtime role. A missing worker never makes a durable `async` message
 disappear, but it leaves the message pending indefinitely.
 
+### 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.
+
 ## Defining an actor
 
 The Durable Object class becomes an ordinary Ruby class:
@@ -503,7 +536,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
@@ -605,26 +638,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
@@ -644,7 +685,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,
@@ -667,6 +708,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:
@@ -798,7 +850,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
 ```
 
@@ -819,7 +875,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
 ```
 
@@ -849,7 +905,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/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.
 
@@ -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
@@ -183,7 +185,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 +428,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 +438,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 +469,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,7 +85,7 @@ 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.
 

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

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,

data/docs/roadmap.md

@@ -4,7 +4,7 @@
 
 - Rails engine, install generator, migration, and CLI
 - Explicit actor registry, references, JSON state, and state migrations
-- Direct synchronous RPC, explicit `sync`, and durable `async`
+- Fluent direct synchronous RPC, configured `sync`, and durable `async`
 - Durable message history plus ready/claimed membership tables
 - Concurrent sequence allocation and actor creation
 - Activation leases, renewal, unique activation tokens, generations, and