fix: scope doctor probe cleanup

Stop the round-trip probe from deregistering and deleting a caller process the application registered, which released its activations and unclaimed its messages. Report cleanup failures as a failed or warned check instead of raising a database lock error out of the command. Instrument component refreshes with identity, key, dependencies, revision, and outcome.

Author: cardmagic

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 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.
+- 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.
+- Instrument component refreshes with actor identity, component name, key,
+  dependencies, refresh method, revision, and outcome, excluding locals.
+
 ## 0.5.0 - 2026-08-07
 
 - Add repeatable reactive components with signed string or integer keys and

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    solid_objects (0.5.0)
+    solid_objects (0.5.1)
       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.5.0)
+  solid_objects (0.5.1)
   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

app/controllers/solid_objects/components_controller.rb

@@ -8,12 +8,25 @@ class ComponentsController < ActionController::Base
 
     # @rbs () -> void
     def show
+      SolidObjects.instrument(:"component.refreshed") { |payload| refresh(payload) }
+    end
+
+    private
+
+    # @rbs (Hash[Symbol, untyped]) -> void
+    def refresh(payload)
       registration = ComponentRegistration.from_token(
         params.require(:token)
       )
+      payload.merge!(registration_payload(registration))
       requested_revision = requested_revision_key
       snapshot = ActorSnapshot.new(registration.reference)
-      return head :conflict if newer_than_snapshot?(requested_revision, snapshot)
+      payload[:instance_id] = snapshot.instance_id
+      payload[:revision] = snapshot.revision
+      if newer_than_snapshot?(requested_revision, snapshot)
+        payload[:outcome] = "conflict"
+        return head :conflict
+      end
 
       authorization_context = SolidObjects
         .configuration
@@ -26,18 +39,32 @@ def show
         authorization_context:
       ).call
       response.headers["Cache-Control"] = "private, no-store"
+      payload[:outcome] = "rendered"
       render html: component_frame(registration, snapshot, rendered)
     rescue Unauthorized
+      payload[:outcome] = "unauthorized"
       head :forbidden
     rescue UnknownComponent
+      payload[:outcome] = "unknown_component"
       head :not_found
     rescue ActionController::ParameterMissing,
       ArgumentError,
       InvalidComponentToken
+      payload[:outcome] = "invalid_token"
       head :bad_request
     end
 
-    private
+    # @rbs (ComponentRegistration) -> Hash[Symbol, untyped]
+    def registration_payload(registration)
+      {
+        actor_type: registration.reference.actor_type,
+        actor_id: registration.reference.actor_id,
+        component_name: registration.component_name,
+        component_key: registration.component_key,
+        dependencies: registration.dependencies,
+        refresh_method: registration.refresh_method
+      }
+    end
 
     # @rbs () -> Array[Integer]
     def requested_revision_key

docs/operations.md

@@ -15,6 +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.
+
 ## Runtime
 
 Start all configured roles:
@@ -147,10 +154,20 @@ transaction rejection, commit-action start/completion/failure, effect and
 broadcast enqueue/completion, reminder enqueue, actor destruction/expiration,
 retention pruning, process cleanup, and supervisor lifecycle.
 
+`solid_objects.component.refreshed` covers every authorized component refresh
+request. Its payload carries the actor identity, `component_name`,
+`component_key`, declared `dependencies`, `refresh_method`, the rendered
+`instance_id` and `revision`, and an `outcome` of `rendered`, `conflict`,
+`unauthorized`, `unknown_component`, or `invalid_token`. Use it to watch
+refresh rate per key, authorization denials, superseded requests, and render
+duration. A rejected token reports only the outcome, since no signed identity
+was recovered.
+
 Payloads contain stable runtime identifiers, actor identity, sequence,
 attempts, ownership generations, and safe exception summaries where relevant.
-Arguments, actor state, results, and outbox payloads are excluded. The bundled
-log subscriber turns the same notifications into structured logger hashes.
+Arguments, component locals, actor state, results, and outbox payloads are
+excluded. The bundled log subscriber turns the same notifications into
+structured logger hashes.
 
 ## Retention and backups
 

lib/solid_objects/caller_process.rb

@@ -26,6 +26,14 @@ 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
@@ -36,6 +44,20 @@ 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,11 +215,22 @@ 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:)
+      return check if leftovers.empty? || check.failed?
+
+      warn_check(
+        :sync_round_trip,
+        "#{check.message}; could not remove the #{leftovers.join(" and ")}"
+      )
+    end
+
+    # @rbs (String) -> Check
+    def run_sync_probe(actor_id)
       value = SecureRandom.hex(8)
-      process_registry = SolidObjects.caller_process.process_registry
-      reference = ProbeActor.ref(actor_id)
       message_reference = Mailbox.new.enqueue(
-        reference,
+        ProbeActor.ref(actor_id),
         :ping,
         { value: },
         kind: "sync"
@@ -230,10 +241,33 @@ def check_sync_round_trip
       pass(:sync_round_trip, "durable synchronous actor call completed without a worker")
     rescue => error
       fail_check(:sync_round_trip, "#{error.class}: #{error.message}")
-    ensure
-      Instance.where(actor_type: ProbeActor.actor_type, actor_id:).delete_all if actor_id
-      process_registry&.stop
-      process_registry&.process_record&.delete
+    end
+
+    # @rbs (actor_id: String, caller_process_id: String?) -> Array[String]
+    def remove_probe_records(actor_id:, caller_process_id:)
+      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
+    end
+
+    # @rbs (String) -> bool
+    def delete_probe_actor(actor_id)
+      Instance.where(actor_type: ProbeActor.actor_type, actor_id:).delete_all
+      true
+    rescue
+      false
+    end
+
+    # @rbs (String) -> bool
+    def delete_probe_caller_process(process_id)
+      SolidObjects.caller_process.delete_process_record(process_id)
+      true
+    rescue
+      false
     end
 
     # @rbs (Check, Check) -> bool

lib/solid_objects/version.rb

@@ -1,5 +1,5 @@
 # rbs_inline: enabled
 
 module SolidObjects
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

sig/generated/controllers/solid_objects/components_controller.rbs

@@ -7,6 +7,12 @@ module SolidObjects
 
     private
 
+    # @rbs (Hash[Symbol, untyped]) -> void
+    def refresh: (Hash[Symbol, untyped]) -> void
+
+    # @rbs (ComponentRegistration) -> Hash[Symbol, untyped]
+    def registration_payload: (ComponentRegistration) -> Hash[Symbol, untyped]
+
     # @rbs () -> Array[Integer]
     def requested_revision_key: () -> Array[Integer]
 

sig/generated/lib/solid_objects/caller_process.rbs

@@ -16,9 +16,15 @@ 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,6 +78,18 @@ module SolidObjects
     # @rbs () -> Check
     def check_sync_round_trip: () -> Check
 
+    # @rbs (String) -> Check
+    def run_sync_probe: (String) -> 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 (String) -> bool
+    def delete_probe_actor: (String) -> bool
+
+    # @rbs (String) -> bool
+    def delete_probe_caller_process: (String) -> bool
+
     # @rbs (Check, Check) -> bool
     def ready_for_round_trip?: (Check, Check) -> bool