solid_objects 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f761acc1e99fba4f747cddd191fc0547ee80c7a30f2e03859f24ff22ab0dd70
-  data.tar.gz: 4ed7f4a52926a5276fa04804ce8fbc142a0c4d9b70641b23b27dc07175956b5e
+  metadata.gz: 8ac17dc212792f2dfa71c01e701a9e4de27f54b6198ec6e64696b855ff82c4c8
+  data.tar.gz: 45bff1ddb2bbc0ff80ddfb55488fec0380d02c729e08a7f06b000b744dddb82d
 SHA512:
-  metadata.gz: 0c63ed0b033d8028041c51c08f4d0bdb8667ab8560d469907474327bbc1536ea561ce00b062ae38f56fc72ded1e9498ecffc55d77bdc4efeaad2d6ffa8953e25
-  data.tar.gz: 9aaa0d27ab02b23c4aa95b05cec82ea4463851f51d2ae9d778058aa93fbaa3a7b6e0c66c3ba3b52efbd3ecefa5079f23bf9d37fe12a9481b0b8b65ecc6b2847b
+  metadata.gz: ffb590f2e07a0de4d4ba2ab5ac1cb7d76420b742d36d656b85ecdb0fc401dbabd92b75e47df73948f7e1d42fe4a289d2f16fa8d86086c8bff336ac4e33ae89dc
+  data.tar.gz: 5a43e24c8358e2352de0ca1428cdc10d15bdf679c62ca1983b420fa1e739d0c975004e0e33ffb64a96fe3d09cbbcd30181db6a95a678c071fd80f85b935811cd

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.5.2 - 2026-08-09
+
+- Read the database clock once per transaction instead of once per step, and
+  resolve the SQLite busy wait from configuration instead of querying the
+  connection for it. A synchronous call now issues 49 database queries instead
+  of 66, which matters most on PostgreSQL and MySQL where every query is a
+  network round trip.
+- Apply every migration in the benchmark harness. It applied only the initial
+  migration, so the `state_revision` column added in 0.4.0 was missing, every
+  message failed at commit, and the synchronous benchmarks timed out.
+
+## 0.5.1 - 2026-08-07
+
+- Restore the SQLite busy wait that a synchronous invocation suspends for its
+  deadline. Rails installs the busy wait as a Ruby busy handler through the
+  sqlite3 `timeout` configuration, which `PRAGMA busy_timeout` reports as zero
+  and silently replaces, so the previous save and restore left pooled
+  connections with no busy handler at all. Every later writer on that
+  connection, inside or outside Solid Objects, then failed immediately with
+  `SQLite3::BusyException` instead of waiting for the lock. Suspend the busy
+  wait only when the adapter can identify how to restore it, so an Active
+  Record release that stops exposing the configured timeout loosens
+  synchronous deadline bounds instead of stripping lock waiting from a shared
+  pooled connection.
+
+- 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.
+- 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

data/app/controllers/solid_objects/components_controller.rb

@@ -8,12 +8,25 @@ module SolidObjects
 
     # @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 @@ module SolidObjects
         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

data/benchmark/support.rb

@@ -228,7 +228,9 @@ module SolidObjectsBenchmark
     # @rbs () -> void
     def migrate
       require_relative "../db/migrate/20260805000000_create_solid_objects_tables"
+      require_relative "../db/migrate/20260806000000_add_state_revision_to_solid_objects_instances"
       CreateSolidObjectsTables.new.migrate(:up)
+      AddStateRevisionToSolidObjectsInstances.new.migrate(:up)
     end
 
     # @rbs () -> void

data/docs/benchmarks.md

@@ -41,6 +41,13 @@ scenario used four worker threads.
 | Synchronous latency | p50 1.8 ms, p95 25.6 ms, p99 156.2 ms |
 | Activation reuse | 98.0%, four activations for 200 messages |
 | Queries for one message turn | 29 |
+| Queries for one synchronous call | 49 |
+
+A synchronous call costs far more queries than a worker turn because the caller
+also registers or heartbeats its caller process, claims the activation, and
+observes the result. Query count, not query time, dominates synchronous latency
+on a networked database: measured locally against SQLite, database time is
+roughly 5% of a call and the remaining 95% is Ruby.
 
 The difference between the SQLite development result and the MySQL adoption
 result is why Solid Objects does not publish one latency promise. Network

data/docs/correctness.md

@@ -167,7 +167,21 @@ 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
+be inspected at timeout. To keep those retries in Ruby, the SQLite adapter
+suspends the connection's busy wait for the duration of each deadline-bound
+transaction and restores it afterwards. Restoration reinstalls the Ruby busy
+handler Rails configures from the sqlite3 `timeout` setting, which
+`PRAGMA busy_timeout` neither reports nor preserves, so a synchronous call
+leaves the connection's lock waiting behaviour exactly as it found it for
+later writers inside and outside Solid Objects.
+
+The adapter suspends the busy wait only when it can identify how to restore
+it. When a future Active Record release stops exposing the configured
+timeout, the adapter leaves the connection untouched: synchronous deadlines
+lose their tight bound and wait as long as the configured busy wait allows,
+rather than stripping lock waiting from a pooled connection the rest of the
+application shares. A test asserts the timeout stays discoverable so the
+looser bound cannot be adopted silently. 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.
 

data/docs/operations.md

@@ -15,6 +15,14 @@ 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 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
 
 Start all configured roles:
@@ -147,10 +155,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
 

data/lib/solid_objects/database_adapter.rb

@@ -4,6 +4,9 @@ require "time"
 
 module SolidObjects
   class DatabaseAdapter
+    TRANSACTION_CLOCK = :solid_objects_transaction_clock
+    TRANSACTION_CLOCK_SCOPE = :solid_objects_transaction_clock_scope
+
     class << self
       # @rbs (untyped) -> DatabaseAdapter
       def for(connection)
@@ -46,10 +49,9 @@ module SolidObjects
 
     # @rbs () -> Time
     def database_now
-      value = with_connection do |connection|
-        connection.select_value("SELECT #{current_time_expression}")
-      end
-      value.is_a?(Time) ? value.utc : Time.parse("#{value} UTC").utc
+      return read_database_now unless ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK_SCOPE]
+
+      ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK] ||= read_database_now
     end
 
     # @rbs () { () -> untyped } -> untyped
@@ -70,7 +72,7 @@ module SolidObjects
         with_transaction_deadline(connection) do
           connection.transaction(requires_new: true) do
             configure_transaction_deadline(connection)
-            block.call
+            with_transaction_clock { block.call }
           end
         end
       end
@@ -91,6 +93,27 @@ module SolidObjects
 
     attr_reader :connection_pool, :fixed_connection
 
+    # @rbs () { () -> untyped } -> untyped
+    def with_transaction_clock
+      return yield if ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK_SCOPE]
+
+      ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK_SCOPE] = true
+      begin
+        yield
+      ensure
+        ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK_SCOPE] = false
+        ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK] = nil
+      end
+    end
+
+    # @rbs () -> Time
+    def read_database_now
+      value = with_connection do |connection|
+        connection.select_value("SELECT #{current_time_expression}")
+      end
+      value.is_a?(Time) ? value.utc : Time.parse("#{value} UTC").utc
+    end
+
     # @rbs (untyped) { () -> untyped } -> untyped
     def with_transaction_deadline(_connection)
       yield

data/lib/solid_objects/database_adapters/sqlite.rb

@@ -67,11 +67,49 @@ module SolidObjects
       def with_transaction_deadline(connection)
         return yield unless SyncDeadline.active?
 
-        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
+        busy_wait = restorable_busy_wait(connection)
+        return yield unless busy_wait
+
+        begin
+          connection.execute("PRAGMA busy_timeout = 0")
+          yield
+        ensure
+          restore_busy_wait(connection, busy_wait)
+        end
+      end
+
+      # @rbs (untyped) -> Hash[Symbol, untyped]?
+      def restorable_busy_wait(connection)
+        handler_timeout = configured_busy_handler_timeout(connection)
+        return { handler_timeout: } if handler_timeout
+
+        pragma_timeout = connection.select_value("PRAGMA busy_timeout").to_i
+        return nil unless pragma_timeout.positive?
+
+        { pragma_timeout: }
+      end
+
+      # @rbs (untyped, Hash[Symbol, untyped]) -> void
+      def restore_busy_wait(connection, busy_wait)
+        handler_timeout = busy_wait[:handler_timeout]
+        if handler_timeout
+          connection.raw_connection.busy_handler_timeout = handler_timeout
+          return
+        end
+
+        connection.execute("PRAGMA busy_timeout = #{busy_wait.fetch(:pragma_timeout)}")
+      end
+
+      # @rbs (untyped) -> Integer?
+      def configured_busy_handler_timeout(connection)
+        return nil unless connection.respond_to?(:raw_connection)
+        return nil unless connection.raw_connection.respond_to?(:busy_handler_timeout=)
+
+        pool = connection.respond_to?(:pool) ? connection.pool : nil
+        return nil unless pool.respond_to?(:db_config)
+
+        timeout = pool.db_config.configuration_hash[:timeout]
+        timeout&.to_i
       end
 
       # @rbs (Exception) -> bool

data/lib/solid_objects/doctor.rb

@@ -215,25 +215,63 @@ module SolidObjects
     # @rbs () -> Check
     def check_sync_round_trip
       actor_id = SecureRandom.uuid
+      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(
+        :sync_round_trip,
+        "#{check.message}; could not remove the #{leftovers.join(" and ")}"
+      )
+    end
+
+    # @rbs (String, ProcessRegistry) -> Check
+    def run_sync_probe(actor_id, probe_registry)
+      probe_registry.register(kind: "caller", metadata: { execution: "doctor" })
       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"
       )
-      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}")
-    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, probe_registry: ProcessRegistry) -> Array[String]
+    def remove_probe_records(actor_id:, probe_registry:)
+      leftovers = []
+      leftovers << "probe actor" unless delete_probe_actor(actor_id)
+      leftovers << "probe caller process" unless delete_probe_caller_process(probe_registry)
+      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 (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
     end
 
     # @rbs (Check, Check) -> bool

data/lib/solid_objects/synchronous_invocation.rb

@@ -6,6 +6,13 @@ require "solid_objects/sync_diagnostics"
 
 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 @@ module SolidObjects
       )
     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)

data/lib/solid_objects/version.rb

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

data/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]
 

data/sig/generated/lib/solid_objects/database_adapter.rbs

@@ -2,6 +2,10 @@
 
 module SolidObjects
   class DatabaseAdapter
+    TRANSACTION_CLOCK: ::Symbol
+
+    TRANSACTION_CLOCK_SCOPE: ::Symbol
+
     # @rbs (untyped) -> DatabaseAdapter
     def self.for: (untyped) -> DatabaseAdapter
 
@@ -42,6 +46,12 @@ module SolidObjects
 
     attr_reader fixed_connection: untyped
 
+    # @rbs () { () -> untyped } -> untyped
+    def with_transaction_clock: () { () -> untyped } -> untyped
+
+    # @rbs () -> Time
+    def read_database_now: () -> Time
+
     # @rbs (untyped) { () -> untyped } -> untyped
     def with_transaction_deadline: (untyped) { () -> untyped } -> untyped
 

data/sig/generated/lib/solid_objects/database_adapters/sqlite.rbs

@@ -26,6 +26,15 @@ module SolidObjects
       # @rbs (untyped) { () -> untyped } -> untyped
       def with_transaction_deadline: (untyped) { () -> untyped } -> untyped
 
+      # @rbs (untyped) -> Hash[Symbol, untyped]?
+      def restorable_busy_wait: (untyped) -> Hash[Symbol, untyped]?
+
+      # @rbs (untyped, Hash[Symbol, untyped]) -> void
+      def restore_busy_wait: (untyped, Hash[Symbol, untyped]) -> void
+
+      # @rbs (untyped) -> Integer?
+      def configured_busy_handler_timeout: (untyped) -> Integer?
+
       # @rbs (Exception) -> bool
       def deadline_error?: (Exception) -> bool
 

data/sig/generated/lib/solid_objects/doctor.rbs

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

data/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
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-07 00:00:00.000000000 Z
+date: 2026-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable