fix: bound sync retries and load actors

Keep SQLite caller bookkeeping and result observation inside the original synchronous deadline without retrying actor behavior.

Load and register host app actors before CLI workers start, including when development eager loading is disabled.

Author: cardmagic

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.3 - 2026-08-07
+
+- Bound SQLite caller-process registration, reuse, heartbeat, and synchronous
+  result observation retries by the original invocation deadline.
+- Load host application actors from `app/actors` before CLI workers start,
+  including development environments with eager loading disabled.
+
 ## 0.4.2 - 2026-08-07
 
 - Decode Action Cable broadcast payloads before parsing observable invalidations

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    solid_objects (0.4.2)
+    solid_objects (0.4.3)
       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.4.2)
+  solid_objects (0.4.3)
   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

@@ -588,9 +588,9 @@ polling as the fallback. A timeout never cancels the durable invocation.
 durable status, mailbox blocker, and activation-owner diagnostics without
 including message arguments. The configured timeout also bounds adapter
 database lock waits from the enqueue attempt through result observation.
-PostgreSQL uses transaction lock and statement timeouts, SQLite uses its busy
-timeout, and MySQL uses its execution timeout plus InnoDB's one-second minimum
-lock-wait granularity.
+PostgreSQL uses transaction lock and statement timeouts, SQLite retries busy
+coordination operations only until the original call deadline, and MySQL uses
+its execution timeout plus InnoDB's one-second minimum lock-wait granularity.
 
 The durable call can finish after its original caller gives up. Reauthorize and
 recover its eventual result through the durable message identity:
@@ -896,6 +896,11 @@ and marks process rows stopped on graceful shutdown. A hard-killed worker's
 claimed turn is recovered after its process heartbeat or activation lease
 becomes stale.
 
+Before any role starts, the CLI loads actors from the host application's
+`app/actors` directories through Rails' main autoloader. This works when
+development eager loading is disabled and does not require actor references in
+an initializer.
+
 See the [operations guide](docs/operations.md) for monitoring, reconciliation,
 shutdown, retention, and backup guidance.
 

docs/correctness.md

@@ -155,10 +155,13 @@ Timeout raises `SolidObjects::SyncTimeout` but does not cancel the message.
 The exception reports actor identity, message ID and sequence, durable status,
 an earlier mailbox blocker, and activation-owner metadata without exposing
 arguments. Its `message_reference` can reauthorize and wait for the eventual
-result. Adapter lock/query deadlines cover the durable enqueue and coordination
-transactions. If enqueue cannot commit, `SyncEnqueueTimeout` is raised and no
-message reference exists. MySQL lock waits have one-second InnoDB granularity.
-Ruby handlers that already started are not preempted.
+result. Adapter lock/query deadlines cover the durable enqueue, caller-process
+registration and heartbeat, activation coordination, and result observation.
+SQLite retries busy coordination operations only within the original call
+deadline and reports `waiting_on=database_contention` when the database cannot
+be inspected at timeout. If enqueue cannot commit, `SyncEnqueueTimeout` is
+raised and no message reference exists. MySQL lock waits have one-second InnoDB
+granularity. Ruby handlers that already started are not preempted.
 
 A synchronous call made while the Solid Objects connection already has an open
 transaction raises `SolidObjects::SyncInsideTransaction` before the message is

docs/operations.md

@@ -23,6 +23,12 @@ Start all configured roles:
 bundle exec solid_objects start
 ```
 
+The command loads the host application's `app/actors` directories before
+starting any runtime role, even when Rails eager loading is disabled. Actors in
+the conventional directory do not need initializer references. The targeted
+loader participates in Rails preparation callbacks so a development reload can
+replace a registered actor class without loading unrelated application code.
+
 Inspect process records and clean stale ownership:
 
 ```bash

lib/solid_objects/activation.rb

@@ -13,7 +13,9 @@ class Activation
     # @rbs (lease: Lease) -> void
     def initialize(lease:)
       @lease = lease
-      instance = Instance.find(lease.instance_id)
+      instance = SolidObjects.database_adapter.with_lock_retry do
+        Instance.find(lease.instance_id)
+      end
       @actor_class = SolidObjects.registry.fetch(instance.actor_type)
       @actor = build_actor(instance)
       @last_used_at = monotonic_now
@@ -74,10 +76,12 @@ def lease_renewal_due?
 
     # @rbs () -> void
     def yield_ready_messages
-      now = SolidObjects.database_adapter.database_now
-      ReadyMessage
-        .where(instance_id: lease.instance_id, available_at: ..now)
-        .update_all(available_at: now)
+      SolidObjects.database_adapter.transaction do
+        now = SolidObjects.database_adapter.database_now
+        ReadyMessage
+          .where(instance_id: lease.instance_id, available_at: ..now)
+          .update_all(available_at: now)
+      end
     end
 
     # @rbs (Hash[String, untyped]) -> void

lib/solid_objects/actor_registry.rb

@@ -18,7 +18,7 @@ def register(type, actor_class)
 
       mutex.synchronize do
         existing = actors[actor_type]
-        if existing && existing != actor_class
+        if existing && existing != actor_class && !reload_of?(existing, actor_class)
           raise InvalidActor, "#{actor_type.inspect} is already registered by #{existing.name}"
         end
 
@@ -61,5 +61,10 @@ def validate_actor_class!(actor_class)
 
       raise InvalidActor, "registered actor must inherit from SolidObjects::Actor"
     end
+
+    # @rbs (Class, Class) -> bool
+    def reload_of?(existing, candidate)
+      !existing.name.nil? && existing.name == candidate.name
+    end
   end
 end

lib/solid_objects/application_actor_loader.rb

@@ -0,0 +1,53 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ApplicationActorLoader
+    # @rbs @application: untyped
+    # @rbs @autoloader: untyped
+
+    # @rbs (?application: untyped, ?autoloader: untyped) -> void
+    def initialize(application: Rails.application, autoloader: Rails.autoloaders.main)
+      @application = application
+      @autoloader = autoloader
+    end
+
+    # @rbs () -> void
+    def call
+      actor_directories.each { |directory| autoloader.eager_load_dir(directory) }
+      current_actor_classes.each(&:ensure_registered!)
+    end
+
+    # @rbs () -> void
+    def install
+      application.reloader.to_prepare { call }
+      call
+    end
+
+    private
+
+    attr_reader :application, :autoloader
+
+    # @rbs () -> Array[String]
+    def actor_directories
+      configured_directories = application.paths["app/actors"]&.existent || []
+      conventional_directories = application.paths["app"].existent.select do |application_directory|
+        File.basename(application_directory) == "actors"
+      end
+      managed_directories = autoloader.dirs.map { |directory| File.expand_path(directory) }
+
+      (configured_directories + conventional_directories)
+        .select { |directory| Dir.exist?(directory) }
+        .map { |directory| File.expand_path(directory) }
+        .select { |directory| managed_directories.include?(directory) }
+        .uniq
+    end
+
+    # @rbs () -> Array[Class]
+    def current_actor_classes
+      Actor.descendants.select do |actor_class|
+        actor_class.name &&
+          actor_class.name.safe_constantize.equal?(actor_class)
+      end
+    end
+  end
+end

lib/solid_objects/caller_process.rb

@@ -52,19 +52,21 @@ def reset_after_fork
     def reusable_registry?
       return false unless registry&.process_record
 
-      registry.process_record.reload.shutdown_state == "running"
+      SolidObjects.database_adapter.with_lock_retry do
+        registry.process_record.reload.shutdown_state == "running"
+      end
     rescue ActiveRecord::RecordNotFound
       false
     end
 
     # @rbs () -> ProcessRegistry
     def register
-      @registry = ProcessRegistry.new
-      registry.register(
+      process_registry = ProcessRegistry.new
+      process_registry.register(
         kind: "caller",
         metadata: { execution: "synchronous" }
       )
-      registry
+      @registry = process_registry
     end
 
     # @rbs () -> void

lib/solid_objects/cli.rb

@@ -1,6 +1,7 @@
 # rbs_inline: enabled
 
 require "thor"
+require "solid_objects/application_actor_loader"
 
 module SolidObjects
   class CLI < Thor
@@ -133,6 +134,7 @@ def boot_application
       end
 
       require path
+      ApplicationActorLoader.new.install
     end
 
     # @rbs (Symbol, Integer) -> Integer