fix: isolate doctor probe caller process

Register a dedicated caller process for the round-trip probe and pass it to SynchronousInvocation, so an overlapping application call can no longer adopt the probe registry and have its activation ownership and claimed messages released when the probe cleans up. Removes the caller process accessors the previous ownership check needed.

Author: cardmagic

CHANGELOG.md

@@ -2,9 +2,10 @@
 
 ## 0.5.1 - 2026-08-07
 
-- Keep the doctor round-trip probe from stopping and deleting a caller process
-  the application registered, which released its activations and unclaimed its
-  messages.
+- Run the doctor round-trip probe on a dedicated caller process, and accept an
+  explicit process registry in `SynchronousInvocation`, so the probe can no
+  longer stop and delete a shared application caller process, release its
+  activations, and unclaim its messages.
 - Report doctor probe cleanup failures as a failed or warned check instead of
   raising a database lock error out of the command and leaking the probe
   caller process.

docs/operations.md

@@ -15,12 +15,13 @@ so the schema check compares the required shape instead of a fixed timestamp.
 Warnings such as an all-deny neutral policy do not fail the command because a
 context-aware production policy may correctly deny the probe.
 
-The round-trip probe cleans up after itself. It removes its temporary actor,
-and removes the caller process record only when the probe registered it, so
-running the doctor inside a process that already serves synchronous calls
-leaves that caller process and its activations untouched. A database busy
-enough to block cleanup reports a failed or warned check rather than raising
-out of the command.
+The round-trip probe runs on its own dedicated caller process rather than the
+shared application caller process, and removes that record together with its
+temporary actor when it finishes. Running the doctor inside a process that
+already serves synchronous calls therefore leaves the application caller
+process, its activations, and its claimed messages untouched, including when an
+application call overlaps the probe. A database busy enough to block cleanup
+reports a failed or warned check rather than raising out of the command.
 
 ## Runtime
 

lib/solid_objects/caller_process.rb

@@ -26,14 +26,6 @@ def process_registry
       end
     end
 
-    # @rbs () -> String?
-    def process_record_id
-      mutex.synchronize do
-        reset_after_fork
-        registry&.process_record&.id
-      end
-    end
-
     # @rbs () -> bool
     def stop
       mutex.synchronize do
@@ -44,20 +36,6 @@ def stop
       end
     end
 
-    # @rbs (String) -> bool
-    def delete_process_record(process_id)
-      mutex.synchronize do
-        reset_after_fork
-        process_record = registry&.process_record
-        return false unless process_record&.id == process_id
-
-        registry.stop
-        process_record.delete
-        @registry = nil
-        true
-      end
-    end
-
     private
 
     attr_reader :mutex, :registry

lib/solid_objects/doctor.rb

@@ -215,9 +215,9 @@ def check_runtime
     # @rbs () -> Check
     def check_sync_round_trip
       actor_id = SecureRandom.uuid
-      caller_process_id = SolidObjects.caller_process.process_record_id
-      check = run_sync_probe(actor_id)
-      leftovers = remove_probe_records(actor_id:, caller_process_id:)
+      probe_registry = ProcessRegistry.new
+      check = run_sync_probe(actor_id, probe_registry)
+      leftovers = remove_probe_records(actor_id:, probe_registry:)
       return check if leftovers.empty? || check.failed?
 
       warn_check(
@@ -226,31 +226,31 @@ def check_sync_round_trip
       )
     end
 
-    # @rbs (String) -> Check
-    def run_sync_probe(actor_id)
+    # @rbs (String, ProcessRegistry) -> Check
+    def run_sync_probe(actor_id, probe_registry)
+      probe_registry.register(kind: "caller", metadata: { execution: "doctor" })
       value = SecureRandom.hex(8)
       message_reference = Mailbox.new.enqueue(
         ProbeActor.ref(actor_id),
         :ping,
         { value: },
         kind: "sync"
       )
-      result = SynchronousInvocation.new.call(message_reference, timeout: 5.seconds)
+      result = SynchronousInvocation
+        .new(process_registry: probe_registry)
+        .call(message_reference, timeout: 5.seconds)
       raise Error, "unexpected round-trip result" unless result == value
 
       pass(:sync_round_trip, "durable synchronous actor call completed without a worker")
     rescue => error
       fail_check(:sync_round_trip, "#{error.class}: #{error.message}")
     end
 
-    # @rbs (actor_id: String, caller_process_id: String?) -> Array[String]
-    def remove_probe_records(actor_id:, caller_process_id:)
+    # @rbs (actor_id: String, probe_registry: ProcessRegistry) -> Array[String]
+    def remove_probe_records(actor_id:, probe_registry:)
       leftovers = []
       leftovers << "probe actor" unless delete_probe_actor(actor_id)
-      probe_process_id = SolidObjects.caller_process.process_record_id
-      return leftovers if probe_process_id.nil? || probe_process_id == caller_process_id
-
-      leftovers << "probe caller process" unless delete_probe_caller_process(probe_process_id)
+      leftovers << "probe caller process" unless delete_probe_caller_process(probe_registry)
       leftovers
     end
 
@@ -262,9 +262,13 @@ def delete_probe_actor(actor_id)
       false
     end
 
-    # @rbs (String) -> bool
-    def delete_probe_caller_process(process_id)
-      SolidObjects.caller_process.delete_process_record(process_id)
+    # @rbs (ProcessRegistry) -> bool
+    def delete_probe_caller_process(probe_registry)
+      process_record = probe_registry.process_record
+      return true unless process_record
+
+      probe_registry.stop
+      process_record.delete
       true
     rescue
       false

lib/solid_objects/synchronous_invocation.rb

@@ -6,6 +6,13 @@
 
 module SolidObjects
   class SynchronousInvocation
+    # @rbs @dedicated_process_registry: ProcessRegistry?
+
+    # @rbs (?process_registry: ProcessRegistry?) -> void
+    def initialize(process_registry: nil)
+      @dedicated_process_registry = process_registry
+    end
+
     # @rbs (MessageReference, timeout: Numeric) -> untyped
     def call(message_reference, timeout:)
       return call_before_deadline(message_reference, timeout:) if SyncDeadline.active?
@@ -92,9 +99,17 @@ def raise_rejection(message)
       )
     end
 
+    # @rbs () -> ProcessRegistry
+    def process_registry
+      dedicated_registry = @dedicated_process_registry
+      return SolidObjects.caller_process.process_registry unless dedicated_registry
+
+      dedicated_registry.tap(&:heartbeat)
+    end
+
     # @rbs (Message, deadline: Float) -> Integer
     def assist(message, deadline:)
-      process_registry = SolidObjects.caller_process.process_registry
+      process_registry = self.process_registry
       activation = ActivationManager
         .new(owner_id: process_registry.process_record.id)
         .claim(instance_id: message.instance_id)

sig/generated/lib/solid_objects/caller_process.rbs

@@ -16,15 +16,9 @@ module SolidObjects
     # @rbs () -> ProcessRegistry
     def process_registry: () -> ProcessRegistry
 
-    # @rbs () -> String?
-    def process_record_id: () -> String?
-
     # @rbs () -> bool
     def stop: () -> bool
 
-    # @rbs (String) -> bool
-    def delete_process_record: (String) -> bool
-
     private
 
     attr_reader mutex: untyped

sig/generated/lib/solid_objects/doctor.rbs

@@ -78,17 +78,17 @@ module SolidObjects
     # @rbs () -> Check
     def check_sync_round_trip: () -> Check
 
-    # @rbs (String) -> Check
-    def run_sync_probe: (String) -> Check
+    # @rbs (String, ProcessRegistry) -> Check
+    def run_sync_probe: (String, ProcessRegistry) -> Check
 
-    # @rbs (actor_id: String, caller_process_id: String?) -> Array[String]
-    def remove_probe_records: (actor_id: String, caller_process_id: String?) -> Array[String]
+    # @rbs (actor_id: String, probe_registry: ProcessRegistry) -> Array[String]
+    def remove_probe_records: (actor_id: String, probe_registry: ProcessRegistry) -> Array[String]
 
     # @rbs (String) -> bool
     def delete_probe_actor: (String) -> bool
 
-    # @rbs (String) -> bool
-    def delete_probe_caller_process: (String) -> bool
+    # @rbs (ProcessRegistry) -> bool
+    def delete_probe_caller_process: (ProcessRegistry) -> bool
 
     # @rbs (Check, Check) -> bool
     def ready_for_round_trip?: (Check, Check) -> bool

sig/generated/lib/solid_objects/synchronous_invocation.rbs

@@ -2,6 +2,11 @@
 
 module SolidObjects
   class SynchronousInvocation
+    @dedicated_process_registry: ProcessRegistry?
+
+    # @rbs (?process_registry: ProcessRegistry?) -> void
+    def initialize: (?process_registry: ProcessRegistry?) -> void
+
     # @rbs (MessageReference, timeout: Numeric) -> untyped
     def call: (MessageReference, timeout: Numeric) -> untyped
 
@@ -22,6 +27,9 @@ module SolidObjects
     # @rbs (Message) -> bot
     def raise_rejection: (Message) -> bot
 
+    # @rbs () -> ProcessRegistry
+    def process_registry: () -> ProcessRegistry
+
     # @rbs (Message, deadline: Float) -> Integer
     def assist: (Message, deadline: Float) -> Integer
 

test/integration/doctor_test.rb

@@ -21,6 +21,19 @@ class DoctorTest < ActiveSupport::TestCase
     assert_empty SolidObjects::Process.where(kind: "caller")
   end
 
+  test "runs its probe on a caller process the application cannot adopt" do
+    SolidObjects.caller_process.define_singleton_method(:process_registry) do
+      raise "the doctor probe must not share the application caller process"
+    end
+
+    report = SolidObjects::Doctor.new.call
+
+    assert_equal :pass, report.check(:sync_round_trip).status
+    assert_empty SolidObjects::Process.where(kind: "caller")
+  ensure
+    SolidObjects.reset_caller_process!
+  end
+
   test "preserves a caller process the application registered before the probe" do
     existing_record = SolidObjects.caller_process.process_registry.process_record
 
@@ -39,10 +52,11 @@ class DoctorTest < ActiveSupport::TestCase
     skip unless SolidObjects::Record.connection.adapter_name.match?(/sqlite/i)
     lock = hold_sqlite_write_lock
 
-    report = SolidObjects::Doctor.new.call
+    report = without_sqlite_busy_wait { SolidObjects::Doctor.new.call }
 
     refute report.healthy?
     assert_equal :fail, report.check(:sync_round_trip).status
+    assert_match(/database is locked/, report.check(:sync_round_trip).message)
   ensure
     release_sqlite_write_lock(lock) if lock
   end
@@ -157,6 +171,16 @@ def hold_sqlite_write_lock
     [ thread, release ]
   end
 
+  def without_sqlite_busy_wait
+    SolidObjects::Record.connection_pool.with_connection do |connection|
+      previous_timeout = connection.select_value("PRAGMA busy_timeout").to_i
+      connection.execute("PRAGMA busy_timeout = 0")
+      yield
+    ensure
+      connection.execute("PRAGMA busy_timeout = #{previous_timeout}") if previous_timeout
+    end
+  end
+
   def release_sqlite_write_lock(lock)
     thread, release = lock
     release << true