fix: load application actors on an ingest miss

Manual QA in a fresh Rails app found the primary use case broken in
development: a controller calling Transmission.receive got
UnknownActorType for every envelope. The ingest looks actors up by
string, and a string cannot trigger the autoload that referencing the
class constant does, so a lazy-loading web process has an empty
registry. Only the CLI installed ApplicationActorLoader.

receive now loads the application's actor classes once on a registry
miss and retries, through an injectable actor_loader: that follows
the mailbox: injection pattern. The first fix attempt also raised
NameError in the web process because application_actor_loader was
required only by the CLI; the gem now requires it, and the load
contract ledger drops its used-only-by-the-CLI row.

QA also showed a conflicting replay returning 500 through the
documented controller, which would make a browser outbox retry a
permanently unappliable envelope forever. IdempotencyConflict joins
the documented 422 rescue list. The transmit docs gain the effect
retry budget: the defaults dead-letter an envelope after roughly
fifteen seconds offline, a dead effect has no retry API, and the
roadmap records that limitation.

Author: cardmagic

CHANGELOG.md

@@ -11,9 +11,11 @@
   `SolidObjects::InvalidTransmission`. Internal delivery skips
   `authorize_message`, so the host application must authenticate the
   request before it calls `receive`; see `docs/transmission.md` for the
-  controller boundary. Golden fixtures in
-  `compatibility/transmit-envelopes.json` pin the wire contract shared with
-  the JS runtime.
+  controller boundary. On a registry miss under Rails, `receive` loads the
+  application's actor classes once and retries, because a lazy-loading web
+  process has no other reason to have loaded the target class. Golden
+  fixtures in `compatibility/transmit-envelopes.json` pin the wire contract
+  shared with the JS runtime.
 - Add `Actor#transmit` and `SolidObjects.register_transmit`, the staging
   side of the transmit family. `transmit.increment(amount:)` stages a
   `solid-objects.transmit` effect in the same commit as the state change;

docs/roadmap.md

@@ -140,7 +140,10 @@
   of who pressed what, and bulk-safe tools: retry is one dead letter at a time,
   because `DeadLetterManager` exposes no bulk operation. Pause is an operator
   brake and not a stop, since a pass already in flight finishes its turn and a
-  synchronous caller waiting on a paused instance times out. The page cost was
+  synchronous caller waiting on a paused instance times out. Retry also only
+  exists for message dead letters: a dead effect or broadcast has no retry
+  API, which matters for transmit effects because a dead one is a lost
+  replay until an operator returns its row to pending. The page cost was
   reasoned about rather than measured: the summary bar issues a fixed set of
   indexed aggregate queries per page, which is why `HEAD /` exists for uptime
   monitors, but no dashboard latency has been benchmarked against a large

docs/transmission.md

@@ -60,6 +60,27 @@ delivers every undelivered sibling for its actor up to its own mailbox
 sequence, oldest first. The receiving side dedups on `transmit:<effectId>`,
 so a redelivered envelope applies once.
 
+## Retry budget and offline tolerance
+
+A raised delivery follows the effect retry policy: `max_attempts` (default
+5) and `retry_delay` (default `2 ** (attempt - 1)` seconds, capped at 60).
+The defaults give roughly fifteen seconds of offline tolerance before an
+envelope dead-letters. An application that transmits across real outages
+must raise both:
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.max_attempts = 30
+  configuration.retry_delay = ->(attempt) { [ 2**(attempt - 1), 300 ].min.to_f }
+end
+```
+
+These settings apply to every effect, not only transmits. A dead transmit
+effect has no retry API; the dashboard lists it, and recovery means
+returning its row to `pending` with a cleared `attempt_count`. Order
+survives that recovery, because the drain orders by mailbox sequence, not
+by retry time.
+
 ## Wire contract
 
 The JS side owns the envelope format. The Ruby ingest accepts it verbatim.
@@ -78,9 +99,12 @@ run a consuming test against the same fixture file.
 
 1. It validates the envelope shape. A malformed envelope raises
    `SolidObjects::InvalidTransmission`.
-2. It resolves the actor type and looks it up in the registry. An unknown
-   type raises `SolidObjects::UnknownActorType`. An undeclared operation
-   raises `SolidObjects::UnknownMessage`.
+2. It resolves the actor type and looks it up in the registry. On a miss
+   under Rails it loads the application's actor classes once and retries,
+   because a lazy-loading process has no other reason to have loaded the
+   target class. A type that is still unknown raises
+   `SolidObjects::UnknownActorType`. An undeclared operation raises
+   `SolidObjects::UnknownMessage`.
 3. It enqueues one internal message with the idempotency key
    `transmit:<effectId>`. Oversized arguments raise
    `SolidObjects::PayloadTooLarge` before persistence.
@@ -105,7 +129,8 @@ class TransmitController < ApplicationController
     SolidObjects::Transmission.receive(JSON.parse(request.body.read))
     head :ok
   rescue SolidObjects::InvalidTransmission, SolidObjects::UnknownActorType,
-    SolidObjects::UnknownMessage, SolidObjects::PayloadTooLarge, JSON::ParserError
+    SolidObjects::UnknownMessage, SolidObjects::PayloadTooLarge,
+    SolidObjects::IdempotencyConflict, JSON::ParserError
     head :unprocessable_entity
   end
 end
@@ -114,6 +139,9 @@ end
 Return 422 for an envelope the server can never apply. The browser outbox
 dead-letters that effect instead of retrying it forever. Return a 5xx for a
 transient server fault, so the browser retries with backoff.
+`SolidObjects::IdempotencyConflict` belongs in the 422 list: it means the
+effect id was replayed with a different invocation, and no retry can ever
+make that envelope apply.
 
 ## Actor type mapping
 

lib/solid_objects.rb

@@ -63,6 +63,7 @@
 # was reachable only through the caller path, so requiring the gem was not
 # enough to run a role that uses it.
 require "solid_objects/mailbox"
+require "solid_objects/application_actor_loader"
 require "solid_objects/transmission"
 require "solid_objects/worker"
 require "solid_objects/effect_executor"

lib/solid_objects/transmission.rb

@@ -8,12 +8,12 @@ module Transmission
     UNDELIVERED_STATUSES = %w[pending processing].freeze
 
     class << self
-      # @rbs (untyped envelope, ?resolve_actor_type: ^(String) -> (String | Symbol), ?mailbox: Mailbox) -> MessageReference
-      def receive(envelope, resolve_actor_type: :itself.to_proc, mailbox: Mailbox.new)
+      # @rbs (untyped envelope, ?resolve_actor_type: ^(String) -> (String | Symbol), ?mailbox: Mailbox, ?actor_loader: ^() -> bool) -> MessageReference
+      def receive(envelope, resolve_actor_type: :itself.to_proc, mailbox: Mailbox.new, actor_loader: method(:load_application_actors))
         validate!(envelope)
 
         actor_type = resolve_actor_type.call(envelope["actorType"]).to_s
-        actor_class = SolidObjects.registry.fetch(actor_type)
+        actor_class = fetch_actor_class(actor_type, actor_loader)
         operation = envelope["operation"].to_sym
         unless actor_class.definition.messages.key?(operation)
           raise UnknownMessage, "unknown operation #{envelope["operation"].inspect}"
@@ -44,6 +44,23 @@ def deliver_through(effect_name:, arguments:, context:, deliver:)
 
       private
 
+      # @rbs (String, ^() -> bool) -> Class
+      def fetch_actor_class(actor_type, actor_loader)
+        SolidObjects.registry.fetch(actor_type)
+      rescue UnknownActorType
+        raise unless actor_loader.call
+
+        SolidObjects.registry.fetch(actor_type)
+      end
+
+      # @rbs () -> bool
+      def load_application_actors
+        return false unless defined?(Rails.application) && Rails.application
+
+        ApplicationActorLoader.new.call
+        true
+      end
+
       # @rbs (Hash[String, untyped], effect_id: String, actor_type: String, actor_id: String) -> Hash[String, untyped]
       def staged_envelope(arguments, effect_id:, actor_type:, actor_id:)
         operation = arguments["operation"]

sig/generated/lib/solid_objects/transmission.rbs

@@ -10,12 +10,18 @@ module SolidObjects
 
     UNDELIVERED_STATUSES: untyped
 
-    # @rbs (untyped envelope, ?resolve_actor_type: ^(String) -> (String | Symbol), ?mailbox: Mailbox) -> MessageReference
-    def self.receive: (untyped envelope, ?resolve_actor_type: ^(String) -> (String | Symbol), ?mailbox: Mailbox) -> MessageReference
+    # @rbs (untyped envelope, ?resolve_actor_type: ^(String) -> (String | Symbol), ?mailbox: Mailbox, ?actor_loader: ^() -> bool) -> MessageReference
+    def self.receive: (untyped envelope, ?resolve_actor_type: ^(String) -> (String | Symbol), ?mailbox: Mailbox, ?actor_loader: ^() -> bool) -> MessageReference
 
     # @rbs (effect_name: String, arguments: Hash[String, untyped], context: EffectContext, deliver: Proc) -> nil
     def self.deliver_through: (effect_name: String, arguments: Hash[String, untyped], context: EffectContext, deliver: Proc) -> nil
 
+    # @rbs (String, ^() -> bool) -> Class
+    private def self.fetch_actor_class: (String, ^() -> bool) -> Class
+
+    # @rbs () -> bool
+    private def self.load_application_actors: () -> bool
+
     # @rbs (Hash[String, untyped], effect_id: String, actor_type: String, actor_id: String) -> Hash[String, untyped]
     private def self.staged_envelope: (Hash[String, untyped], effect_id: String, actor_type: String, actor_id: String) -> Hash[String, untyped]
 

test/integration/load_contract_test.rb

@@ -13,7 +13,6 @@ class LoadContractTest < ActiveSupport::TestCase
   # else that stops being loaded is a role waiting to fail in production, so
   # this list is the place to argue that a role never reaches it.
   DEFERRED = {
-    "application_actor_loader" => "used only by the CLI",
     "caller_process" => "the caller path, required by SolidObjects.caller_process",
     "cli" => "loaded by exe/solid_objects, and pulls in thor",
     "client" => "the caller path, required by SolidObjects.client",

test/integration/transmission_test.rb

@@ -86,6 +86,23 @@ def valid_envelope(overrides = {})
     assert_equal "transmit-counters", SolidObjects::Message.sole.actor_type
   end
 
+  test "loads application actors on a registry miss before failing" do
+    loaded = false
+    loader = -> do
+      loaded = true
+      SolidObjects.register_actor("lazy-counters", CounterActor)
+      true
+    end
+
+    SolidObjects::Transmission.receive(
+      valid_envelope("actorType" => "lazy-counters"),
+      actor_loader: loader
+    )
+
+    assert loaded
+    assert_equal "lazy-counters", SolidObjects::Message.sole.actor_type
+  end
+
   test "rejects an unknown actor type" do
     assert_raises(SolidObjects::UnknownActorType) do
       SolidObjects::Transmission.receive(valid_envelope("actorType" => "missing"))