solid_objects 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf365fb1bf63f59d2e13544271d9c86adfb37b6f4ea962c8a38befbd4f2ef53d
-  data.tar.gz: ab3e2a3b06f43e9257bc4415edc371e23c652a8616be8a08b5d217b599fce7bc
+  metadata.gz: 654720ae19caa970f403b5cded61287e1f6a9eb9d731ff90fd9f4f103d55fa53
+  data.tar.gz: 256712423dd88685643a0345de44eb774efbca12188c78c9e89571ef884b59fc
 SHA512:
-  metadata.gz: 1c9992bce15fd9b1edacffe02e9f5fc5558e98853a3ae206b08ddd3753a5b28874c6ea73134af03e27dadb093b13c59ccb6a1f564efa2613a386a913b7d182b1
-  data.tar.gz: 71eaf3e7c278be7f1f2277ad753bb36421f90895da9ee3f9289178c4b5c7f10c180526504571d49d08a7d0437174353376b71c7801d9d46e3df169b3881e3a15
+  metadata.gz: f1e43da5f13c33558bdb187b52c55b55093786d3ec8af9f49d4ffc123ade274d2f5483dd8975c6a638152dfc9ae1c4cf416d8b1ea94cb1383ac30b33ef7548aa
+  data.tar.gz: f8cb10850b5b3748450ffaf741417866ed360437657c5d21836312018f0d6b27109cd69c4035f770f6cf643227ab086ae7eedc1b0a14245103cfe517a008f49c

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.2.1 - 2026-08-06
+
+- Add `solid_objects:doctor` for configuration, schema, policy, runtime, and
+  workerless synchronous round-trip verification.
+- Add onboarding guidance for fit decisions, worker requirements,
+  authorization, performance and row growth, retention, Sorbet, RuboCop, and
+  migrations from existing state stores.
+- Make the early-Action View engine boot regression explicit.
+
+## 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

@@ -20,8 +20,13 @@ class Counter < SolidObjects::Actor
   end
 end
 
-# from anywhere in your app — addressed by name:
-Counter.ref("global").increment(amount: 5)
+# Synchronous caller-assisted RPC. No worker fleet is required.
+counter = Counter.ref("global")
+count = counter.increment(amount: 5)
+current_count = counter.value
+
+# Durable fire-and-forget delivery. A worker processes it later.
+message = counter.async(:increment, amount: 5)
 ```
 
 `Counter / global` is a logical identity. Like a Durable Object named with
@@ -30,11 +35,28 @@ locating a Ruby object. Solid Objects activates it when work arrives, commits
 its ordered turns one at a time, persists its state, and deactivates it when
 idle. Different identities can run concurrently.
 
+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.value` | Deeply frozen state snapshot | No |
+| `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
+worker. `async` only enqueues; a runtime process handles it later.
+
+Before adopting a latency-sensitive or high-volume surface, read
+[Is Solid Objects a good fit?](docs/fit.md) and the
+[measured performance and row-growth costs](docs/benchmarks.md).
+
 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).
 
@@ -43,9 +65,10 @@ but the project does not yet claim production readiness. See
 - [Cloudflare Durable Objects for Rails](#cloudflare-durable-objects-for-rails)
 - [Reactive ERB](#reactive-erb)
 - [Installation](#installation)
+- [Worker requirements](#worker-requirements)
 - [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 +194,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
@@ -187,10 +210,17 @@ Add the gem, install its initializer and migration, then migrate:
 bundle add solid_objects
 bin/rails generate solid_objects:install
 bin/rails db:migrate
+bin/rails solid_objects:doctor
 ```
 
-The generated initializer denies all externally initiated operations. Replace
-the policy blocks with application-specific authorization before sending
+The doctor validates configuration and required schema shape, reports
+authorization posture and live runtime roles, and completes a real synchronous
+actor round-trip without a worker. It checks required tables and columns instead
+of a copied migration timestamp, which the host application rewrites. It exits
+unsuccessfully when configuration, schema, or the round-trip is broken.
+
+The generated initializer is intentionally inert: all five policies deny by
+default. Replace them with application-specific authorization before sending
 messages, querying state, destroying actors, subscribing to streams, or
 mounting administration routes:
 
@@ -205,15 +235,62 @@ end
 ```
 
 Knowledge of an actor ID or signed stream token is never authorization.
+Read the [policy reference and tenant-aware example](docs/authorization.md)
+before opening a policy. Unconditionally allowing message and query calls is
+reasonable only for a controlled server-side pilot. Keep destroy,
+subscription, and administration denied until each has an authenticated
+caller.
+
+The engine uses the application's primary Active Record connection by default.
+See [Database support](#database-support) for a separate database configuration.
+
+### Host application tooling
+
+Installed engine migrations are copied as
+`db/migrate/*_create_solid_objects_tables.solid_objects.rb`. If the host enables
+`Rails/CreateTableWithTimestamps`, exclude engine-owned migrations rather than
+editing their intentionally specialized hot tables:
+
+```yaml
+Rails/CreateTableWithTimestamps:
+  Exclude:
+    - "db/migrate/*.solid_objects.rb"
+```
+
+Solid Objects ships inline RBS signatures, not RBI files. Sorbet applications
+can generate the gem RBI with:
+
+```bash
+bundle exec tapioca gem solid_objects
+```
+
+## Worker requirements
 
-Start the runtime:
+Synchronous actors can be adopted without adding a long-running process. Start
+the runtime when the feature introduces asynchronous delivery or outboxes:
+
+| Feature | Runtime roles required |
+| --- | --- |
+| Direct actor method or explicit `sync` | None; the caller executes it |
+| Attribute or declared query read | None; the caller executes it |
+| `destroy` | None |
+| `async` including delayed delivery | Actor worker |
+| One-shot or recurring `schedule` | Reminder scheduler and actor worker |
+| `emit` without an actor callback | Effect worker |
+| `emit` with success or failure callback | Effect worker and actor worker |
+| Actor-to-actor `async` or `send_to` | Effect worker and actor worker |
+| Observable Turbo updates | Broadcast worker, Action Cable, and the actor execution path |
+| Initial `solid_object` server render | No Solid Objects worker; normal Rails rendering |
+
+One command starts every Solid Objects role:
 
 ```bash
 bundle exec solid_objects start
 ```
 
-The engine uses the application's primary Active Record connection by default.
-See [Database support](#database-support) for a separate database configuration.
+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.
 
 ## Defining an actor
 
@@ -251,18 +328,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 +389,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 +404,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.
+
+The `message(:name) { ... }` and `query(:name) { ... }` DSLs remain available
+for dynamic definitions.
 
-### `tell`
+### `async`
 
-`tell` durably enqueues work and immediately returns a message reference:
+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 +433,48 @@ 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
 
-Actor code cannot call `ask`; synchronous actor-to-actor waits can deadlock in
-cycles. Use `tell` or `send_to` and a result message.
+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
+```
+
+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.
+
+`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`.
 
 ### Redelivery
 
@@ -445,7 +552,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 +621,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 +740,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.
@@ -659,6 +766,13 @@ Do not use it for stateless work, bulk pipelines, CPU-heavy computation,
 cross-actor transactions, slow network calls inside handlers, or domains that
 are clearer as normalized Active Record models and direct service objects.
 
+High-QPS request reads, rate-limit counters, impression pipelines, large JSON
+documents, and latency budgets that cannot tolerate several coordination
+transactions are explicit anti-patterns. Read the full
+[fit and anti-pattern guide](docs/fit.md) before migrating an existing
+surface, and use the [legacy-state migration cookbook](docs/migrating-existing-state.md)
+for staged cutovers.
+
 ## Comparisons
 
 | Tool | What Solid Objects adds or changes |
@@ -700,15 +814,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/adoption_latency.rb

@@ -0,0 +1,5 @@
+# rbs_inline: enabled
+
+require_relative "support"
+
+SolidObjectsBenchmark.adoption_latency

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,51 @@ 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 adoption_latency
+      instance_count = SolidObjects::Instance.count
+      message_count = SolidObjects::Message.count
+
+      cold_elapsed = Benchmark.realtime do
+        CounterActor.ref("adoption-cold").increment
+      end
+
+      reference = CounterActor.ref("adoption-warm")
+      reference.increment
+      write_samples = Array.new(count) do
+        Benchmark.realtime { reference.increment }
+      end
+      read_samples = Array.new(count) do
+        Benchmark.realtime { reference.count }
+      end
+
+      puts "first cold call: #{milliseconds(cold_elapsed)}ms"
+      puts latency_summary("warm writes", write_samples)
+      puts latency_summary("ordered reads", read_samples)
+      puts "durable row growth: " \
+        "instances=+#{SolidObjects::Instance.count - instance_count}, " \
+        "messages=+#{SolidObjects::Message.count - message_count}"
     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 +191,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 +253,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
@@ -260,6 +281,15 @@ module SolidObjectsBenchmark
       samples.fetch(((samples.length - 1) * fraction).ceil)
     end
 
+    # @rbs (String, Array[Float]) -> String
+    def latency_summary(name, samples)
+      sorted = samples.sort
+      "#{name} #{samples.length} calls: " \
+        "median=#{milliseconds(percentile(sorted, 0.50))}ms " \
+        "min=#{milliseconds(sorted.first)}ms " \
+        "max=#{milliseconds(sorted.last)}ms"
+    end
+
     # @rbs (Float) -> String
     def milliseconds(seconds)
       format("%.1f", seconds * 1_000)

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.