solid_objects 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf365fb1bf63f59d2e13544271d9c86adfb37b6f4ea962c8a38befbd4f2ef53d
-  data.tar.gz: ab3e2a3b06f43e9257bc4415edc371e23c652a8616be8a08b5d217b599fce7bc
+  metadata.gz: 4d95ae7c1b6791ce00951e73eaf535a7b0b357c6708112509544de82eb59314d
+  data.tar.gz: a6a9ef715c217e38959438d1ab549447e0814c621746967dece190ae46b3108b
 SHA512:
-  metadata.gz: 1c9992bce15fd9b1edacffe02e9f5fc5558e98853a3ae206b08ddd3753a5b28874c6ea73134af03e27dadb093b13c59ccb6a1f564efa2613a386a913b7d182b1
-  data.tar.gz: 71eaf3e7c278be7f1f2277ad753bb36421f90895da9ee3f9289178c4b5c7f10c180526504571d49d08a7d0437174353376b71c7801d9d46e3df169b3881e3a15
+  metadata.gz: d604e195d678ae5f2ae24932fd0431a7076d0f8258b9e064bbc463042b911512edc7a6b613673b6731256d0b0603311708beb2158d79e421dc85b5febfb37f4d
+  data.tar.gz: cd817466462c8d0c843fa9766df1f2190ed3b477466661e32a47859f7fc63349327af7cb077d75ab5a43b621bb3ee98e321363b007ff5ad19e311123d871e040

data/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.

data/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

data/app/models/solid_objects/claimed_message.rb

@@ -10,5 +10,7 @@ module SolidObjects
       class_name: "SolidObjects::Process",
       foreign_key: :process_id,
       optional: true
+
+    validates :activation_token, presence: true, if: :process_id?
   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[tell ask internal] }
+    validates :message_kind, inclusion: { in: %w[async sync internal] }
 
     # @rbs () -> bool
     def ready?
@@ -37,6 +37,11 @@ module SolidObjects
       completed_at.present?
     end
 
+    # @rbs () -> bool
+    def rejected?
+      rejected_at.present?
+    end
+
     # @rbs () -> bool
     def dead?
       dead_letter.present?

data/benchmark/support.rb

@@ -61,13 +61,13 @@ module SolidObjectsBenchmark
     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 @@ module SolidObjectsBenchmark
 
     # @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 @@ module SolidObjectsBenchmark
     # @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 @@ module SolidObjectsBenchmark
     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 @@ module SolidObjectsBenchmark
 
     # @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 @@ 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].tell(:increment) }
+      count.times { |index| references[index % actor_count].async(:increment) }
     end
 
     # @rbs (SolidObjects::Worker) -> Integer

data/benchmark/{ask_latency.rb → sync_latency.rb}

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

data/db/migrate/20260805000000_create_solid_objects_tables.rb

@@ -60,6 +60,7 @@ class CreateSolidObjectsTables < ActiveRecord::Migration[8.0]
       definition.integer :state_version, null: false, default: 1
       definition.bigint :next_message_sequence, null: false, default: 1
       definition.string :activation_owner_id, limit: 36
+      definition.string :activation_token, limit: 36
       definition.datetime :activation_expires_at, precision: 6
       definition.bigint :activation_generation, null: false, default: 0
       definition.datetime :activated_at, precision: 6
@@ -75,12 +76,17 @@ class CreateSolidObjectsTables < ActiveRecord::Migration[8.0]
       definition.check_constraint "state_version > 0", name: "chk_so_instances_state_version"
       definition.check_constraint "next_message_sequence > 0", name: "chk_so_instances_sequence"
       definition.check_constraint "activation_generation >= 0", name: "chk_so_instances_generation"
+      definition.check_constraint(
+        "(activation_owner_id IS NULL AND activation_token IS NULL) OR " \
+          "(activation_owner_id IS NOT NULL AND activation_token IS NOT NULL)",
+        name: "chk_so_instances_activation_owner"
+      )
     end
 
     add_foreign_key table(:instances),
       table(:processes),
       column: :activation_owner_id,
-      on_delete: :nullify,
+      on_delete: :restrict,
       name: "fk_so_instances_owner"
   end
 
@@ -102,10 +108,12 @@ class CreateSolidObjectsTables < ActiveRecord::Migration[8.0]
       definition.string :idempotency_key, limit: 191
       json_column definition, :result
       json_column definition, :error
+      json_column definition, :rejection
       definition.datetime :enqueued_at, null: false, precision: 6
       definition.datetime :available_at, null: false, precision: 6
       definition.datetime :started_at, precision: 6
       definition.datetime :completed_at, precision: 6
+      definition.datetime :rejected_at, precision: 6
       definition.datetime :last_failed_at, precision: 6
       definition.timestamps precision: 6, null: false
 
@@ -114,10 +122,11 @@ class CreateSolidObjectsTables < ActiveRecord::Migration[8.0]
       definition.index :request_id, unique: true, name: "idx_so_messages_request"
       definition.index [ :instance_id, :idempotency_key ], unique: true, name: "idx_so_messages_idempotency"
       definition.index [ :completed_at, :id ], name: "idx_so_messages_cleanup"
+      definition.index [ :rejected_at, :id ], name: "idx_so_messages_rejected"
       definition.check_constraint "sequence > 0", name: "chk_so_messages_sequence"
       definition.check_constraint "attempt_count >= 0", name: "chk_so_messages_attempt"
       definition.check_constraint "max_attempts > 0", name: "chk_so_messages_max_attempts"
-      definition.check_constraint "message_kind IN ('tell', 'ask', 'internal')", name: "chk_so_messages_kind"
+      definition.check_constraint "message_kind IN ('async', 'sync', 'internal')", name: "chk_so_messages_kind"
     end
   end
 
@@ -148,6 +157,7 @@ class CreateSolidObjectsTables < ActiveRecord::Migration[8.0]
         null: false,
         foreign_key: { to_table: table(:instances), on_delete: :cascade, name: "fk_so_claimed_instance" }
       definition.string :process_id, limit: 36
+      definition.string :activation_token, limit: 36
       definition.bigint :activation_generation, null: false
       definition.datetime :claimed_at, null: false, precision: 6
 
@@ -155,12 +165,14 @@ class CreateSolidObjectsTables < ActiveRecord::Migration[8.0]
       definition.index :instance_id, unique: true, name: "idx_so_claimed_instance"
       definition.index [ :process_id, :claimed_at ], name: "idx_so_claimed_process"
       definition.check_constraint "activation_generation > 0", name: "chk_so_claimed_generation"
+      definition.check_constraint "process_id IS NULL OR activation_token IS NOT NULL",
+        name: "chk_so_claimed_activation_owner"
     end
 
     add_foreign_key table(:claimed_messages),
       table(:processes),
       column: :process_id,
-      on_delete: :nullify,
+      on_delete: :restrict,
       name: "fk_so_claimed_process"
   end
 

data/docs/adr/0006-at-least-once-delivery.md

@@ -21,4 +21,4 @@ Message handlers themselves can run more than once. Sequential execution means o
 - Pure state transitions are safe because failed transactions roll back.
 - Application handlers need durable state guards for non-repeatable logical transitions.
 - External systems require idempotency keys or deduplication.
-- `ask` timing out does not cancel its durable message.
+- A synchronous invocation timing out does not cancel its durable message.

data/docs/adr/0008-actor-communication.md

@@ -9,7 +9,10 @@ If actor A synchronously waits for actor B while B waits for A, sequential actor
 
 ## Decision
 
-Actor references support durable asynchronous `tell`. `ask` is a caller-facing request/response operation and must not be called from actor code. Actor code uses staged actor messages or request/result message pairs.
+Actor references support durable asynchronous delivery through `async`.
+Direct methods and `sync` are caller-facing request/response operations and
+must not be called from actor code. Actor code uses staged actor messages or
+request/result message pairs.
 
 Messages staged during actor execution are delivered through a transactional outbox so they exist if and only if the source message commits.
 

data/docs/adr/0011-wake-up-strategy.md

@@ -9,7 +9,8 @@ Polling adds latency and database queries. PostgreSQL notifications are transact
 
 ## Decision
 
-Database rows remain the only durable source of work and results. Wake-up adapters only tell workers and `ask` waiters to re-query those rows.
+Database rows remain the only durable source of work and results. Wake-up
+adapters only prompt workers and synchronous waiters to re-query those rows.
 
 The interface supports:
 
@@ -20,9 +21,17 @@ The interface supports:
 
 MySQL uses polling or optional Redis. SQLite uses polling plus the in-process signal; multi-host SQLite is outside its supported operating model.
 
-The coordination-overhead latency budget, measured from durable enqueue or completion commit until a waiting worker or caller begins its confirming query, is p99 at or below 100 milliseconds when a healthy cross-process wake-up adapter is enabled. Polling-only deployments accept up to the configured polling interval on each wait leg. End-to-end `ask` latency additionally includes queueing and actor execution and cannot have a library-wide bound.
-
-Polling-only `ask` is intended for background callers, scripts, and control paths. It is not recommended in latency-sensitive Rails request handlers. A request handler may use it only with an explicit timeout and an operationally verified wake-up adapter and actor latency budget.
+The synchronous caller first attempts to claim and execute the actor locally,
+so the normal path has no worker polling leg. When another process owns the
+activation, coordination overhead from completion commit until the caller's
+confirming query targets p99 at or below 100 milliseconds with a healthy
+cross-process wake-up adapter. Polling fallback accepts up to
+`sync_polling_interval` between observations. End-to-end latency still includes
+earlier mailbox work and actor execution and cannot have a library-wide bound.
+
+Direct methods and `sync` are intended for HTTP, MCP, scripts, and control
+paths whose handler and mailbox latency fit an explicit application budget.
+Timeout does not cancel durable work.
 
 ## Consequences