feat: add synchronous actor RPC

Make direct actor methods caller-assisted synchronous invocations while preserving durable mailbox ordering, leases, and fencing. Add explicit async delivery, terminal domain rejection, unique activation tokens, and the early Action View engine boot fix. Update the portable schema, tests, signatures, benchmarks, and release documentation for 0.2.0.

Author: cardmagic

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.0 - 2026-08-06
+
+- Make direct actor methods synchronous Durable Object-style RPC.
+- Add explicit `sync` and `async` invocation modes.
+- Let synchronous callers assist execution through the ordered mailbox using
+  the same activation leases and fencing checks as workers.
+- Add terminal domain rejections that roll back actor state without retrying or
+  creating dead letters.
+- Give each activation a unique token so concurrent callers in one process
+  cannot share lease ownership.
+- Fix Action View helper loading when Action View initializes before engine
+  autoload paths.
+
 ## 0.1.0 - 2026-08-06
 
 - Introduce the Rails engine, actor API, and `solid_objects` executable.

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    solid_objects (0.1.0)
+    solid_objects (0.2.0)
       actioncable (>= 8.0)
       actionpack (>= 8.0)
       actionview (>= 8.0)
@@ -373,7 +373,7 @@ CHECKSUMS
   rubocop-rails-omakase (1.1.0) sha256=2af73ac8ee5852de2919abbd2618af9c15c19b512c4cfc1f9a5d3b6ef009109d
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
-  solid_objects (0.1.0)
+  solid_objects (0.2.0)
   sqlite3 (2.9.5-aarch64-linux-gnu) sha256=78075b6337d3d182c6d2b4691049ed45cd220826160c9ea18946bf6a1de200dc
   sqlite3 (2.9.5-aarch64-linux-musl) sha256=18c801185deb4adc01ddb281e8f672a39e3d1729979ca91e39439cd3eac0402d
   sqlite3 (2.9.5-arm-linux-gnu) sha256=1bdfca0c7d63998c60b0f4a8e3c8df2d33800ccc4abd2d612eddbbbc92a4c48b

README.md

@@ -34,7 +34,7 @@ This is a port of the programming model, not Cloudflare's edge runtime or
 platform. Read the conceptual overview at [solidobjects.dev](https://solidobjects.dev/)
 and the exact Rails guarantees in [Correctness and delivery semantics](docs/correctness.md).
 
-Version 0.1 is an early release. Its correctness core is implemented and tested,
+Version 0.2 is an early release. Its correctness core is implemented and tested,
 but the project does not yet claim production readiness. See
 [Status](#status) and the [roadmap](docs/roadmap.md).
 
@@ -45,7 +45,7 @@ but the project does not yet claim production readiness. See
 - [Installation](#installation)
 - [Defining an actor](#defining-an-actor)
 - [Actor identity](#actor-identity)
-- [Messages and queries](#messages-and-queries)
+- [Invoking an object](#invoking-an-object)
 - [Effects](#effects)
 - [Reminders](#reminders)
 - [Destroying an object](#destroying-an-object)
@@ -171,7 +171,7 @@ refresh from current actor state.
 `cart.component(:summary)` supports initial rendering of
 `actors/shopping_cart/_summary`. Durable live component replacement and
 Turbo append actions are roadmap work; observable replacement is the live path
-implemented in 0.1.
+implemented in 0.2.
 
 Reactive views require `turbo-rails` and a working Action Cable adapter in the
 host application. They are optional; the actor runtime itself does not depend
@@ -206,7 +206,8 @@ end
 
 Knowledge of an actor ID or signed stream token is never authorization.
 
-Start the runtime:
+Start the runtime for asynchronous messages, effects, reminders, and
+broadcasts:
 
 ```bash
 bundle exec solid_objects start
@@ -251,18 +252,20 @@ declared on the actor are durable message handlers. They can use `items`,
 `self.checkout_status = "pending"`, or the lower-level `state` object. Declare
 helper methods as private or protected so they are not exposed as messages.
 
-Attributes also become ordered read queries on a reference. Declared messages
-become asynchronous methods:
+Attributes also become ordered read queries on a reference. Public actor
+methods and attribute readers are synchronous caller-assisted invocations:
 
 ```ruby
 cart = ShoppingCart.ref("alice")
-message = cart.add_item(product_id: "shirt-123", quantity: 2)
+cart.add_item(product_id: "shirt-123", quantity: 2)
 items = cart.items
 ```
 
-`message` is a `SolidObjects::MessageReference`. `items` is a deeply frozen
-JSON snapshot; mutating it cannot bypass the actor mailbox. State changes must
-go through public actor message methods.
+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
+`async`.
 
 State, arguments, results, effects, and reminder arguments accept
 JSON-compatible values. Solid Objects never deserializes Ruby `Marshal` data.
@@ -310,7 +313,7 @@ end
 Actor types resolve only through the explicit registry. Solid Objects never
 constantizes a type supplied by a client.
 
-## Messages and queries
+## Invoking an object
 
 As with a Durable Object stub, declared actor operations are available directly
 on a reference:
@@ -325,24 +328,27 @@ class Counter < SolidObjects::Actor
 end
 
 counter = Counter.ref("global")
-message = counter.increment(amount: 5)
+value = counter.increment(amount: 5)
 value = counter.value
 ```
 
-Public actor methods are messages and become asynchronous syntax over `tell`,
-returning a durable `MessageReference`. Declared queries and attribute readers
-are synchronous syntax over `ask`. Unlike Cloudflare RPC, the initial `ask`
-implementation waits by polling the durable database row.
-The `message(:name) { ... }` DSL remains available for dynamic definitions.
-The explicit `tell` and `ask` forms remain available for dynamic operation
-names or names that collide with Ruby or reference methods.
+Like RPC on a Durable Object stub, a direct call is synchronous from the
+caller's perspective. Solid Objects first durably enqueues the invocation, then
+executes that actor locally when its fenced activation is available. It returns
+the committed, deeply frozen result. Earlier mailbox entries still run first,
+and a remote worker may win the activation without changing the result
+semantics.
 
-### `tell`
+The `message(:name) { ... }` and `query(:name) { ... }` DSLs remain available
+for dynamic definitions.
 
-`tell` durably enqueues work and immediately returns a message reference:
+### `async`
+
+Use `async` for durable fire-and-forget work. It returns a
+`MessageReference` immediately and leaves execution to the worker fleet:
 
 ```ruby
-message = order.tell(
+message = order.async(
   :submit,
   idempotency_key: "submit-order-123"
 )
@@ -351,23 +357,44 @@ message = order.tell(
 Use `available_at:` to spread bulk work or delay one message:
 
 ```ruby
-order.tell(:evaluate, available_at: 10.minutes.from_now)
+order.async(:evaluate, available_at: 10.minutes.from_now)
 ```
 
-### `ask`
+### `sync`
 
-`ask` durably enqueues a query or message and waits for its result:
+Use explicit `sync` when the operation name is dynamic or collides with a
+reference method:
 
 ```ruby
-status = order.ask(:status, timeout: 5.seconds)
+status = order.sync(:status, timeout: 5.seconds)
 ```
 
-The initial cross-process implementation polls the durable message row. It is
-intended for background callers and control paths, not latency-sensitive HTTP
-request handling. A timeout does not cancel the actor message.
+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
+application's latency budget. If another process owns the activation, the
+caller waits for the durable result using wake-up hints with bounded database
+polling as the fallback. A timeout never cancels the durable invocation.
+
+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.
+
+### Domain rejection
+
+Reject invalid input without retrying or creating a dead letter:
+
+```ruby
+def submit(response:)
+  reject :validation_failed, "Response is not valid" unless valid?(response)
+
+  self.response = response
+end
+```
 
-Actor code cannot call `ask`; synchronous actor-to-actor waits can deadlock in
-cycles. Use `tell` or `send_to` and a result message.
+The caller receives `SolidObjects::Rejected` with a stable code, message, and
+JSON-compatible details. The rejected message remains durable for audit, actor
+state is rolled back, and no later mailbox turn is blocked.
 
 ### Redelivery
 
@@ -445,7 +472,7 @@ enqueue each one.
 
 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 `tell`. Never bulk-update actor
+`.orphaned`, but every repair must go through `async`. Never bulk-update actor
 state around the lease and fencing checks.
 
 ## Destroying an object
@@ -514,7 +541,7 @@ Important defaults:
 | Setting | Default |
 | --- | ---: |
 | `polling_interval` | 0.1 seconds |
-| `ask_polling_interval` | 0.05 seconds |
+| `sync_polling_interval` | 0.05 seconds |
 | `lease_duration` | 30 seconds |
 | `lease_renewal_interval` | 10 seconds |
 | `idle_deactivation_timeout` | 30 seconds |
@@ -633,7 +660,7 @@ Solid Objects does not promise:
 - global order across actors;
 - distributed transactions;
 - bounded end-to-end latency;
-- cancellation when an `ask` caller times out; or
+- cancellation when a synchronous caller times out; or
 - that a lease prevents stale Ruby code from continuing to run.
 
 The fencing generation prevents stale code from committing.
@@ -700,15 +727,18 @@ See the [development guide](docs/development.md) and
 
 ## Status
 
-Implemented and tested in 0.1:
+Implemented and tested in 0.2:
 
 - Rails engine, install generator, migrations, and `solid_objects` executable;
 - actor registry, references, JSON state, and state migrations;
+- direct synchronous actor RPC, explicit `sync`, and durable `async`;
 - durable message history plus ready and claimed membership tables;
 - concurrent sequence allocation and actor creation;
-- activation leases, renewal, fencing generations, and stale-write rejection;
+- activation leases, per-activation tokens, fencing generations, and
+  stale-write rejection;
 - bounded activation passes, idle activation cache, and hot-actor fairness;
-- retries, strict poison ordering, dead letters, and retry tooling;
+- retries, terminal domain rejection, strict poison ordering, dead letters,
+  and retry tooling;
 - transactional effects and asynchronous actor-to-actor messages;
 - one-shot and recurring per-actor reminders;
 - authorized actor destruction with fenced stale-write rejection and cascading

app/models/solid_objects/claimed_message.rb

@@ -10,5 +10,7 @@ class ClaimedMessage < Record
       class_name: "SolidObjects::Process",
       foreign_key: :process_id,
       optional: true
+
+    validates :activation_token, presence: true, if: :process_id?
   end
 end

app/models/solid_objects/message.rb

@@ -20,7 +20,7 @@ class Message < Record
 
     before_validation :supply_defaults
 
-    validates :message_kind, inclusion: { in: %w[tell ask internal] }
+    validates :message_kind, inclusion: { in: %w[async sync internal] }
 
     # @rbs () -> bool
     def ready?
@@ -37,6 +37,11 @@ def completed?
       completed_at.present?
     end
 
+    # @rbs () -> bool
+    def rejected?
+      rejected_at.present?
+    end
+
     # @rbs () -> bool
     def dead?
       dead_letter.present?

benchmark/support.rb

@@ -61,13 +61,13 @@ def measure(name)
     def enqueue
       reference = CounterActor.ref("enqueue")
       measure("enqueue #{count} messages") do
-        count.times { reference.tell(:increment) }
+        count.times { reference.async(:increment) }
       end
     end
 
     # @rbs () -> void
     def claim
-      count.times { |index| CounterActor.ref("claim-#{index}").tell(: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:)
@@ -100,7 +100,7 @@ def processing
 
     # @rbs () -> void
     def cold_actors
-      count.times { |index| CounterActor.ref("cold-#{index}").tell(:increment) }
+      count.times { |index| CounterActor.ref("cold-#{index}").async(:increment) }
       worker = SolidObjects::Worker.new
       measure("process #{count} cold actors") { drain(worker) }
     ensure
@@ -110,7 +110,7 @@ def cold_actors
     # @rbs () -> void
     def hot_actor
       reference = CounterActor.ref("hot")
-      count.times { reference.tell(:increment) }
+      count.times { reference.async(:increment) }
       worker = SolidObjects::Worker.new
       measure("process #{count} messages for one hot actor") { drain(worker) }
     ensure
@@ -130,30 +130,25 @@ def concurrent_actors
     end
 
     # @rbs () -> void
-    def ask_latency
-      worker = SolidObjects::Worker.new
-      worker_thread = Thread.new { worker.run }
+    def sync_latency
       samples = []
 
       count.times do |index|
         started_at = monotonic_now
-        CounterActor.ref("ask-#{index}").ask(:count, timeout: 5)
+        CounterActor.ref("sync-#{index}").sync(:count, timeout: 5)
         samples << monotonic_now - started_at
       end
 
       sorted = samples.sort
-      puts "ask #{count} calls: p50=#{milliseconds(percentile(sorted, 0.50))}ms " \
+      puts "sync #{count} calls: p50=#{milliseconds(percentile(sorted, 0.50))}ms " \
         "p95=#{milliseconds(percentile(sorted, 0.95))}ms " \
         "p99=#{milliseconds(percentile(sorted, 0.99))}ms"
-    ensure
-      worker&.request_shutdown
-      worker_thread&.join
     end
 
     # @rbs () -> void
     def activation_cache
       reference = CounterActor.ref("cache")
-      count.times { reference.tell(:increment) }
+      count.times { reference.async(:increment) }
       activations = 0
       subscriber = ActiveSupport::Notifications.subscribe("solid_objects.activation.started") do
         activations += 1
@@ -170,7 +165,7 @@ def activation_cache
 
     # @rbs () -> void
     def query_count
-      CounterActor.ref("queries").tell(:increment)
+      CounterActor.ref("queries").async(:increment)
       worker = SolidObjects::Worker.new
       queries = 0
       subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |event|
@@ -232,7 +227,7 @@ def load_models
     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].tell(:increment) }
+      count.times { |index| references[index % actor_count].async(:increment) }
     end
 
     # @rbs (SolidObjects::Worker) -> Integer

benchmark/ask_latency.rb benchmark/sync_latency.rbbenchmark/ask_latency.rb renamed to benchmark/sync_latency.rb

@@ -2,4 +2,4 @@
 
 require_relative "support"
 
-SolidObjectsBenchmark.ask_latency
+SolidObjectsBenchmark.sync_latency