fix: harden fluent actor dispatch

Reject operation names that collide with dispatcher methods so every declared operation is either callable or rejected at definition time.\n\nUse operation and delivery-mode terminology through persistence and make multi-argument internal APIs keyword-only for clearer call sites. Keep the original schema migration immutable and carry the column renames in a new migration.

Author: cardmagic

CHANGELOG.md

@@ -13,6 +13,11 @@
 - 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

app/controllers/solid_objects/components_controller.rb

@@ -55,7 +55,7 @@ def refresh_batch(payload)
           "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 @@ def refresh(payload)
       ).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 @@ def component_view_context
       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

app/models/solid_objects/message.rb

@@ -20,7 +20,7 @@ class Message < Record
 
     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?

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>

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>

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

docs/architecture.md

@@ -71,7 +71,7 @@ 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.
 
@@ -185,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.

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.

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.
 

lib/solid_objects.rb

@@ -21,8 +21,8 @@
 require "solid_objects/context"
 require "solid_objects/actor_registry"
 require "solid_objects/state"
-require "solid_objects/actor_definition"
 require "solid_objects/operation_dispatcher"
+require "solid_objects/actor_definition"
 require "solid_objects/application_write_guard"
 require "solid_objects/actor"
 require "solid_objects/reference"