solid_objects 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de78ca94f2c12e3c08d50c7b2512d6dbda67a47571540390c7494c6a828f1d35
-  data.tar.gz: b194c137ff3110cabb6cb2f7319819fdd64f314a9ae2113868438a89acce36b8
+  metadata.gz: 17e88ea06322a5e262d146e3d96a0b0d54d2339d46c6681a2fdb0f8d244a3640
+  data.tar.gz: d33b76b4e741921b4e199f3f91af652c06217960606dc7e3e95a03b28d34d3db
 SHA512:
-  metadata.gz: 78834ecb346469854b6d21d938fe3a6ed2689cd60cb037b22b3ce00025466c172ceb3dacdfcf94f88b0e0739e3dcac1c3e84896c6685bc4fe53d4db565ab8513
-  data.tar.gz: 31fbae44dce542e1fc07fe218bf504eb8627583ecc64895e8d86a5805340aeea47531b5f08a6e844809c31b513998c53c28b90993ae9cd40b864e868323eee27
+  metadata.gz: 0a217bfdb8454acbf7caa7a153095455e8b421aab4ebc7a16be056efa49db78bc4e0c452f50e24c04f1aad5177aafdb16ebff67a974618a0134c302581edf85a
+  data.tar.gz: 284a15eb44417ebaad3ec0ccad3b180999ed94df9d7ca73b74fcc70ed136f3458613ecbadb99115f13e93310d684a0451a62f6887dd7b0c2bdcf1af14ade2fcf

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.8.0 - 2026-08-10
+
+- Replace a supervised role whose thread died. A role that raised left its
+  thread dead while the process kept running and quietly did less work; the
+  supervisor now restarts it until shutdown is requested. Prune dead process
+  records on an interval as part of the same monitor. Both intervals are
+  configurable through `supervisor_monitor_interval` and
+  `dead_process_cleanup_interval`.
+- Run compatibility CI across the span the gemspec advertises: Ruby 3.3 and 3.4
+  against Rails 8.0 and 8.1. The suite previously ran on one combination, so
+  `>= 8.0` was a claim rather than a tested guarantee. Set `RAILS_VERSION` to
+  pin a Rails line locally.
+- Stop a synchronous lock retry from asking for a negative wait when its
+  deadline expires between the check and the wait, which raised
+  `ArgumentError: time interval must not be negative` instead of the timeout
+  the caller expected. Found by the new compatibility matrix.
+- Add `SolidObjects::WakeUpAdapters::Postgresql`, an optional cross-process
+  wake-up using PostgreSQL notifications. In-process signalling cannot reach a
+  worker process, so reactive delivery waited out `polling_interval`. With the
+  adapter configured, measured cross-process wake-up latency drops from 103.7 ms
+  to 2.9 ms at p50. The polling interval remains the upper bound, and neither
+  signalling nor waiting raises into its caller. `WakeUpAdapters.for` selects
+  notifications on PostgreSQL and the in-process default elsewhere; it is not
+  the default, because the adapter opens a connection per waiting thread
+  outside the pool and `LISTEN` does not survive a transaction-pooling proxy.
+
 ## 0.7.3 - 2026-08-09
 
 - Coordinate batched component refreshes by revision as well as scope and batch

data/docs/benchmarks.md

@@ -76,6 +76,21 @@ Cable delivery, or browser rendering, which dominate wall-clock time in a real
 deployment and make the request-count difference matter more than it appears
 here. End-to-end latency against a deployed application has not been measured.
 
+## Cross-process wake-up
+
+Measured 2026-08-09 against PostgreSQL 17, 30 samples, with `polling_interval`
+at its 100 ms default and a signal sent 2 ms after the waiter began.
+
+| Wake-up strategy | p50 | p95 |
+| --- | ---: | ---: |
+| In-process `WakeUp` | 103.7 ms | 105.1 ms |
+| `WakeUpAdapters::Postgresql` | 2.9 ms | 5.1 ms |
+
+The in-process wake-up cannot reach another process, so a worker waits out the
+full polling interval no matter how quickly the web process committed. The
+notification adapter removes that floor rather than shrinking it, and the
+polling interval remains the upper bound if a notification is missed.
+
 ## Durable row growth
 
 The storage cost is deterministic even when latency is not:

data/docs/realtime.md

@@ -110,6 +110,36 @@ applications discover the namespaced engine asset. Applications created with
 explicitly serve the module. Turbo's normal morph rules still apply; use
 `data-turbo-permanent` for elements that must never be changed.
 
+## Cross-process wake-up
+
+Runtime roles poll for work and are woken early by an in-process signal. That
+signal cannot cross process boundaries, so a commit in a Puma process does not
+wake a broadcast executor in a worker process, and delivery waits out
+`polling_interval`, 100 ms by default.
+
+On PostgreSQL, install the notification adapter to remove that delay:
+
+```ruby
+# config/initializers/solid_objects.rb
+configuration.wake_up_adapter = SolidObjects::WakeUpAdapters.for
+```
+
+`WakeUpAdapters.for` returns notifications on PostgreSQL and the in-process
+default on SQLite and MySQL, so the same line is safe across adapters. Name
+`SolidObjects::WakeUpAdapters::Postgresql.new` directly to require it.
+
+MySQL has no notification primitive, so MySQL applications keep polling and tune
+`polling_interval`.
+
+Measured latency for a cross-process wake-up drops from 103.7 ms to 2.9 ms at
+p50. The adapter keeps `polling_interval` as the upper bound: a missed or failed
+notification costs latency, never correctness, and signalling never raises into
+the caller that committed. `LISTEN` needs its own connection, so the adapter
+opens one outside the pool and releases it on `stop`.
+
+Applications on SQLite or MySQL, or that do not configure the adapter, keep the
+existing polling behaviour.
+
 ## Batched component refreshes
 
 A component refresh costs one browser request. When one actor mutation changes

data/docs/roadmap.md

@@ -31,23 +31,32 @@
 - Bounded message/process pruning, actor-type opt-in instance expiration,
   graceful caller shutdown, committed state snapshots, and an opt-in Minitest
   helper
+- Supervisor role replacement: a role whose thread dies is restarted until
+  shutdown is requested, and dead process records are pruned on an interval
 - SQLite, PostgreSQL, and MySQL integration suites
+- Opt-in cross-process wake-up on PostgreSQL through `WakeUpAdapters.for`, with
+  a listening connection per waiting thread and release on supervisor shutdown
 - Inline RBS generation/validation, Steep, Standard Ruby, Solid Queue's exact
   RuboCop policy, and a warning-free Brakeman scan
+- Compatibility CI across the supported span: Ruby 3.3 and 3.4 against Rails 8.0
+  and 8.1, pinned through `RAILS_VERSION` so the advertised range is verified
+  rather than assumed
 - A JavaScript suite covering the state payload and batched refresh browser
   modules, run in CI with Node's test runner and jsdom, with every GitHub
   Actions reference pinned to a commit SHA
 
 ## Partially implemented
 
-- Supervisor: starts and drains thread roles, but does not replace a crashed
-  role or run periodic maintenance automatically.
-- Wake-up strategy: in-process signaling plus durable polling and injection are
-  implemented; PostgreSQL `LISTEN/NOTIFY` and optional Redis adapters are not.
-  Signaling cannot cross process boundaries, so a commit in a web process does
-  not wake a broadcast executor in a worker process; that delivery waits up to
-  `polling_interval`, 100 ms by default. This is the largest remaining term in
-  reactive update latency, and neither batching nor state payloads reduce it.
+- Wake-up strategy: in-process signaling, durable polling, injection, and an
+  opt-in PostgreSQL notification adapter are implemented; a Redis adapter is
+  not. In-process signaling cannot cross process boundaries, so without the
+  adapter a commit in a web process does not wake a broadcast executor in a
+  worker process and that delivery waits up to `polling_interval`, 100 ms by
+  default. `WakeUpAdapters.for` removes that delay on PostgreSQL, measured at
+  103.7 ms to 2.9 ms at p50. It is opt-in rather than automatic: it opens a
+  connection per waiting thread outside the pool, and `LISTEN` does not survive
+  a transaction-pooling proxy such as PgBouncer. MySQL has no notification
+  primitive, so MySQL applications keep polling.
 - Realtime: scalar and dependency-driven keyed ERB component replacement or
   morphing, personalized refresh authorization, revision fencing, coalescing,
   reconnect convergence, batched refreshes, and personalized state payloads are
@@ -67,19 +76,18 @@
 
 ## Next milestones
 
-1. Add automatic supervisor role replacement and periodic dead-process cleanup.
-2. Add PostgreSQL notification and optional Redis wake-up adapters with latency
-   benchmarks and polling-race tests, removing the cross-process polling delay
-   rather than shrinking it with a smaller `polling_interval`.
-3. Add result lookup by request ID and broader deadlock retry classification.
-4. Add scheduled retention and stale-process maintenance.
-5. Add database/server-version checks and MySQL InnoDB verification at boot.
-6. Add Turbo append intents and expand reconnect coverage in a full browser.
-7. Add distributed rate limits, global admission hooks, and cache-capacity
+1. Add an optional Redis wake-up adapter, which is the remaining cross-process
+   option for MySQL. The PostgreSQL notification adapter, its latency
+   benchmark, and its concurrency tests are implemented.
+2. Add result lookup by request ID and broader deadlock retry classification.
+3. Add scheduled retention and stale-process maintenance.
+4. Add database/server-version checks and MySQL InnoDB verification at boot.
+5. Add Turbo append intents and expand reconnect coverage in a full browser.
+6. Add distributed rate limits, global admission hooks, and cache-capacity
    eviction.
-8. Expand security scanning and run compatibility CI across supported Rails and
+7. Expand security scanning and run compatibility CI across supported Rails and
    Ruby versions.
-9. Benchmark all workloads under documented hardware/database settings and
+8. Benchmark all workloads under documented hardware/database settings and
    publish adapter-specific adoption measurements. Throughput, synchronous
    latency, query counts, and the three reactive delivery paths are measured on
    SQLite; adapter-specific and end-to-end browser measurements are not.

data/lib/generators/solid_objects/templates/solid_objects.rb

@@ -58,4 +58,12 @@ SolidObjects.configure do |configuration|
   # configuration.authorize_administration = lambda do |authorization_context:, **|
   #   authorization_context.is_a?(Hash) && authorization_context[:source] == "cli"
   # end
+
+  # Runtime roles poll for work and are woken early by an in-process signal,
+  # which cannot reach another process. On PostgreSQL, notifications remove that
+  # delay. This opens a connection per waiting thread outside the pool and does
+  # not work through a transaction-pooling proxy such as PgBouncer, so it is
+  # opt-in:
+  #
+  # configuration.wake_up_adapter = SolidObjects::WakeUpAdapters.for
 end

data/lib/solid_objects/configuration.rb

@@ -21,6 +21,8 @@ module SolidObjects
     # @rbs @process_heartbeat_interval: Float
     # @rbs @process_alive_threshold: Float
     # @rbs @shutdown_timeout: Float
+    # @rbs @supervisor_monitor_interval: Float
+    # @rbs @dead_process_cleanup_interval: Float
     # @rbs @message_retention: Numeric
     # @rbs @message_retention_by_actor_type: Hash[String, Numeric]
     # @rbs @instance_retention_by_actor_type: Hash[String, Numeric]
@@ -62,6 +64,8 @@ module SolidObjects
       :process_heartbeat_interval,
       :process_alive_threshold,
       :shutdown_timeout,
+      :supervisor_monitor_interval,
+      :dead_process_cleanup_interval,
       :message_retention,
       :message_retention_by_actor_type,
       :instance_retention_by_actor_type,
@@ -102,6 +106,8 @@ module SolidObjects
       @max_attempts = 5
       @retry_delay = ->(attempt) { [ 2**(attempt - 1), 60 ].min.to_f }
       @lock_retry_attempts = 10
+      @supervisor_monitor_interval = 1.0
+      @dead_process_cleanup_interval = 60.0
       @process_heartbeat_interval = 15.0
       @process_alive_threshold = 60.0
       @shutdown_timeout = 15.0
@@ -138,6 +144,10 @@ module SolidObjects
         raise ArgumentError, "table_name_prefix must contain lowercase letters, digits, and underscores"
       end
 
+      unless supervisor_monitor_interval.positive?
+        raise ArgumentError, "supervisor_monitor_interval must be positive"
+      end
+
       unless lease_duration > lease_renewal_interval
         raise ArgumentError, "lease_duration must be greater than lease_renewal_interval"
       end

data/lib/solid_objects/database_adapters/sqlite.rb

@@ -160,13 +160,15 @@ module SolidObjects
         end
       end
 
+      # The deadline can expire between the check above and this wait, which
+      # would otherwise ask for a negative interval.
       # @rbs () -> void
       def wait_before_retry
+        interval = [ LOCK_RETRY_INTERVAL, SyncDeadline.remaining ].min
+        return unless interval.positive?
+
         LOCK_RETRY_MUTEX.synchronize do
-          LOCK_RETRY_CONDITION.wait(
-            LOCK_RETRY_MUTEX,
-            [ LOCK_RETRY_INTERVAL, SyncDeadline.remaining ].min
-          )
+          LOCK_RETRY_CONDITION.wait(LOCK_RETRY_MUTEX, interval)
         end
       end
     end

data/lib/solid_objects/supervisor.rb

@@ -4,7 +4,10 @@ module SolidObjects
   class Supervisor
     # @rbs @components: Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
     # @rbs @threads: Array[Thread]
+    # @rbs @monitor: Thread?
     # @rbs @started: bool
+    # @rbs @cleaned_up_at: Float
+    # @rbs @lifecycle: Thread::Mutex
 
     # @rbs (?worker_count: Integer, ?effect_worker_count: Integer, ?broadcast_worker_count: Integer, ?reminder_scheduler_count: Integer) -> void
     def initialize(
@@ -20,7 +23,10 @@ module SolidObjects
         reminder_scheduler_count:
       )
       @threads = []
+      @monitor = nil
       @started = false
+      @cleaned_up_at = nil
+      @lifecycle = Thread::Mutex.new
     end
 
     # @rbs () -> void
@@ -36,7 +42,8 @@ module SolidObjects
       return if @started
 
       @started = true
-      @threads = components.map { |component| Thread.new { component.run } }
+      @threads = components.map { |component| supervise(component) }
+      @monitor = Thread.new { monitor_loop }
       SolidObjects.instrument(:"supervisor.started", component_count: components.length)
     end
 
@@ -44,17 +51,129 @@ module SolidObjects
     def stop
       return unless @started
 
-      components.each(&:request_shutdown)
-      join_until_timeout
-      components.reject(&:stopped?).each(&:stop)
-      @started = false
-      SolidObjects.instrument(:"supervisor.stopped", component_count: components.length)
+      begin
+        # Flipping the flag under the same lock replacement takes means a
+        # replacement either completes before shutdown reads the component
+        # list, or never starts.
+        @lifecycle.synchronize { @started = false }
+        stop_monitor
+        components.each(&:request_shutdown)
+        join_until_timeout
+        components.reject(&:stopped?).each(&:stop)
+      ensure
+        # Connections held outside the pool must be released even when a
+        # component fails to stop, or they accumulate across restarts.
+        release_wake_up
+        @monitor = nil
+        SolidObjects.instrument(:"supervisor.stopped", component_count: components.length)
+      end
     end
 
     private
 
     attr_reader :components, :threads
 
+    # A role that raises leaves its thread dead. Without replacement the
+    # process keeps running while quietly doing less work, so the supervisor
+    # watches its threads and restarts any that stopped before shutdown.
+    # A failing pass must not stop supervision, and must not retry without
+    # pacing either: a persistently failing database would otherwise spin.
+    # @rbs () -> void
+    def monitor_loop
+      while @started
+        begin
+          replace_dead_roles
+          cleanup_dead_processes
+        rescue => error
+          SolidObjects.instrument(
+            :"supervisor.monitor_failed",
+            error_class: error.class.name,
+            error_message: error.message
+          )
+        end
+        sleep SolidObjects.configuration.supervisor_monitor_interval
+      end
+    end
+
+    # A role that raises runs its own shutdown cleanup on the way out, so a
+    # crashed component reports itself stopped exactly like one that was asked
+    # to stop. While the supervisor is still running, a dead thread can only
+    # mean a crash, so replacement keys on the supervisor rather than on the
+    # component. The crashed instance has already released its process record,
+    # so a fresh one takes its place.
+    # @rbs () -> void
+    def replace_dead_roles
+      components.each_with_index do |component, index|
+        thread = threads[index]
+        next if thread&.alive?
+
+        replaced = @lifecycle.synchronize do
+          next false unless @started
+
+          replacement = component.class.new
+          components[index] = replacement
+          threads[index] = supervise(replacement)
+          replacement
+        end
+        break unless replaced
+
+        SolidObjects.instrument(
+          :"supervisor.role_replaced",
+          role: replaced.class.name,
+          error_class: thread_error(thread)
+        )
+      end
+    end
+
+    # @rbs (Thread?) -> String?
+    def thread_error(thread)
+      thread&.join
+      nil
+    rescue => error
+      error.class.name
+    end
+
+    # @rbs () -> void
+    def cleanup_dead_processes
+      interval = SolidObjects.configuration.dead_process_cleanup_interval
+      return unless interval.positive?
+      return if @cleaned_up_at && monotonic_now - @cleaned_up_at < interval
+
+      @cleaned_up_at = monotonic_now
+      ProcessRegistry.cleanup_dead
+    end
+
+    # @rbs (untyped) -> Thread
+    def supervise(component)
+      Thread.new { component.run }
+    end
+
+    # The monitor only performs maintenance, so shutdown must never return while
+    # it is still alive: a pass blocked on the database would otherwise outlive
+    # the supervisor that owns it.
+    # @rbs () -> void
+    def stop_monitor
+      monitor = @monitor
+      @monitor = nil
+      return unless monitor
+
+      monitor.join(SolidObjects.configuration.shutdown_timeout)
+      monitor.kill if monitor.alive?
+      monitor.join(SolidObjects.configuration.supervisor_monitor_interval)
+    end
+
+    # A wake-up adapter may hold connections outside the pool, which would
+    # otherwise accumulate across restarts in one process.
+    # @rbs () -> void
+    def release_wake_up
+      wake_up = SolidObjects.wake_up
+      return unless wake_up.respond_to?(:stop)
+
+      wake_up.stop
+    rescue
+      nil
+    end
+
     # @rbs (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
     def build_components(
       worker_count:,

data/lib/solid_objects/version.rb

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

data/lib/solid_objects/wake_up_adapters/postgresql.rb

@@ -0,0 +1,136 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module WakeUpAdapters
+    # Wakes runtime roles across processes using PostgreSQL notifications.
+    #
+    # The in-process wake-up cannot reach another process, so a commit in a web
+    # process leaves a worker waiting out its polling interval. This adapter
+    # keeps that polling interval as the upper bound and delivers a notification
+    # when one is available, so a missed or failed notification costs latency
+    # rather than correctness.
+    class Postgresql
+      CHANNEL = "solid_objects_wake_up"
+      FAILED_WAIT_INTERVAL = 0.05
+
+      # @rbs @channel: String
+      # @rbs @mutex: Thread::Mutex
+      # @rbs @connections: Array[untyped]
+
+      attr_reader :channel
+
+      # @rbs (?channel: String) -> void
+      def initialize(channel: CHANNEL)
+        @channel = channel
+        @mutex = Thread::Mutex.new
+        @connections = []
+      end
+
+      # @rbs () -> bool
+      def signal
+        notify_channel
+        true
+      rescue => error
+        instrument_failure(:signal, error)
+        false
+      end
+
+      # @rbs (timeout: Numeric) -> bool
+      def wait(timeout:)
+        connection = listening_connection
+        !connection.raw_connection.wait_for_notify(timeout.to_f).nil?
+      rescue => error
+        instrument_failure(:wait, error)
+        pace_after_failure(timeout)
+        false
+      end
+
+      # Starts listening before a caller blocks, so a notification sent between
+      # startup and the first wait is not missed.
+      # @rbs () -> bool
+      def listen
+        listening_connection
+        true
+      rescue => error
+        instrument_failure(:listen, error)
+        false
+      end
+
+      # @rbs () -> bool
+      def stop
+        open = mutex.synchronize do
+          listening = connections.dup
+          connections.clear
+          listening
+        end
+        Thread.current[thread_key] = nil
+        open.each { |connection| disconnect(connection) }
+        open.any?
+      end
+
+      private
+
+      attr_reader :mutex, :connections
+
+      # @rbs () -> void
+      def notify_channel
+        Record.connection_pool.with_connection do |connection|
+          connection.execute("NOTIFY #{connection.quote_table_name(channel)}")
+        end
+      end
+
+      # A listening connection is dedicated and per thread. `LISTEN` is per
+      # connection, a blocking wait must not hold a connection the rest of the
+      # runtime needs, and one connection cannot serve concurrent waiters: the
+      # supervisor shares one adapter across roles, and a notification consumed
+      # by one waiter would leave the others asleep until their poll expired.
+      # @rbs () -> untyped
+      def listening_connection
+        connection = Thread.current[thread_key]
+        return connection if connection&.active?
+
+        open_listening_connection
+      end
+
+      # @rbs () -> untyped
+      def open_listening_connection
+        connection = Record.connection_pool.send(:new_connection)
+        connection.execute("LISTEN #{connection.quote_table_name(channel)}")
+        Thread.current[thread_key] = connection
+        mutex.synchronize { connections << connection }
+        connection
+      end
+
+      # @rbs () -> Symbol
+      def thread_key
+        :"solid_objects_wake_up_#{object_id}"
+      end
+
+      # @rbs (untyped) -> void
+      def disconnect(connection)
+        connection.disconnect!
+      rescue
+        nil
+      end
+
+      # @rbs (Numeric) -> void
+      def pace_after_failure(timeout)
+        interval = [ timeout.to_f, FAILED_WAIT_INTERVAL ].min
+        return unless interval.positive?
+
+        sleep interval
+      end
+
+      # @rbs (Symbol, Exception) -> void
+      def instrument_failure(operation, error)
+        SolidObjects.instrument(
+          :"wake_up.failed",
+          adapter: "postgresql",
+          operation: operation.to_s,
+          error_class: error.class.name,
+          error_message: error.message
+        )
+      end
+    end
+  end
+end

data/lib/solid_objects/wake_up_adapters.rb

@@ -0,0 +1,23 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module WakeUpAdapters
+    module_function
+
+    # Returns the best wake-up strategy for a connection: cross-process
+    # notifications where the database provides them, and the in-process
+    # default everywhere else.
+    #
+    # This is deliberately not the default. A notification adapter opens a
+    # connection per waiting thread outside the pool, and `LISTEN` does not
+    # survive a transaction-pooling proxy such as PgBouncer, so adopting it is
+    # a deployment decision rather than an upgrade side effect.
+    #
+    # @rbs (?untyped) -> untyped
+    def for(connection = Record.connection)
+      return Postgresql.new if connection.adapter_name.match?(/postgres/i)
+
+      WakeUp.new
+    end
+  end
+end

data/lib/solid_objects.rb

@@ -46,6 +46,8 @@ require "solid_objects/actor_view"
 require "solid_objects/actor_channel"
 require "solid_objects/action_cable_broadcast_adapter"
 require "solid_objects/wake_up"
+require "solid_objects/wake_up_adapters/postgresql"
+require "solid_objects/wake_up_adapters"
 require "solid_objects/effect_registry"
 require "solid_objects/commit_action_registry"
 require "solid_objects/lease"

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

@@ -2,10 +2,12 @@
 
 module SolidObjects
   class Configuration
-    @process_alive_threshold: Float
-
     @shutdown_timeout: Float
 
+    @supervisor_monitor_interval: Float
+
+    @dead_process_cleanup_interval: Float
+
     @message_retention: Numeric
 
     @message_retention_by_actor_type: Hash[String, Numeric]
@@ -82,6 +84,8 @@ module SolidObjects
 
     @process_heartbeat_interval: Float
 
+    @process_alive_threshold: Float
+
     attr_accessor table_name_prefix: untyped
 
     attr_accessor polling_interval: untyped
@@ -120,6 +124,10 @@ module SolidObjects
 
     attr_accessor shutdown_timeout: untyped
 
+    attr_accessor supervisor_monitor_interval: untyped
+
+    attr_accessor dead_process_cleanup_interval: untyped
+
     attr_accessor message_retention: untyped
 
     attr_accessor message_retention_by_actor_type: untyped

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

@@ -52,6 +52,8 @@ module SolidObjects
       # @rbs (Integer) -> void
       def wait_before_busy_retry: (Integer) -> void
 
+      # The deadline can expire between the check above and this wait, which
+      # would otherwise ask for a negative interval.
       # @rbs () -> void
       def wait_before_retry: () -> void
     end

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

@@ -2,12 +2,18 @@
 
 module SolidObjects
   class Supervisor
-    @components: Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
+    @lifecycle: Thread::Mutex
 
-    @threads: Array[Thread]
+    @cleaned_up_at: Float
 
     @started: bool
 
+    @monitor: Thread?
+
+    @threads: Array[Thread]
+
+    @components: Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
+
     # @rbs (?worker_count: Integer, ?effect_worker_count: Integer, ?broadcast_worker_count: Integer, ?reminder_scheduler_count: Integer) -> void
     def initialize: (?worker_count: Integer, ?effect_worker_count: Integer, ?broadcast_worker_count: Integer, ?reminder_scheduler_count: Integer) -> void
 
@@ -26,6 +32,43 @@ module SolidObjects
 
     attr_reader threads: untyped
 
+    # A role that raises leaves its thread dead. Without replacement the
+    # process keeps running while quietly doing less work, so the supervisor
+    # watches its threads and restarts any that stopped before shutdown.
+    # A failing pass must not stop supervision, and must not retry without
+    # pacing either: a persistently failing database would otherwise spin.
+    # @rbs () -> void
+    def monitor_loop: () -> void
+
+    # A role that raises runs its own shutdown cleanup on the way out, so a
+    # crashed component reports itself stopped exactly like one that was asked
+    # to stop. While the supervisor is still running, a dead thread can only
+    # mean a crash, so replacement keys on the supervisor rather than on the
+    # component. The crashed instance has already released its process record,
+    # so a fresh one takes its place.
+    # @rbs () -> void
+    def replace_dead_roles: () -> void
+
+    # @rbs (Thread?) -> String?
+    def thread_error: (Thread?) -> String?
+
+    # @rbs () -> void
+    def cleanup_dead_processes: () -> void
+
+    # @rbs (untyped) -> Thread
+    def supervise: (untyped) -> Thread
+
+    # The monitor only performs maintenance, so shutdown must never return while
+    # it is still alive: a pass blocked on the database would otherwise outlive
+    # the supervisor that owns it.
+    # @rbs () -> void
+    def stop_monitor: () -> void
+
+    # A wake-up adapter may hold connections outside the pool, which would
+    # otherwise accumulate across restarts in one process.
+    # @rbs () -> void
+    def release_wake_up: () -> void
+
     # @rbs (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
     def build_components: (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
 

data/sig/generated/lib/solid_objects/wake_up_adapters/postgresql.rbs

@@ -0,0 +1,75 @@
+# Generated from lib/solid_objects/wake_up_adapters/postgresql.rb with RBS::Inline
+
+module SolidObjects
+  module WakeUpAdapters
+    # Wakes runtime roles across processes using PostgreSQL notifications.
+    #
+    # The in-process wake-up cannot reach another process, so a commit in a web
+    # process leaves a worker waiting out its polling interval. This adapter
+    # keeps that polling interval as the upper bound and delivers a notification
+    # when one is available, so a missed or failed notification costs latency
+    # rather than correctness.
+    class Postgresql
+      CHANNEL: ::String
+
+      FAILED_WAIT_INTERVAL: ::Float
+
+      @connections: Array[untyped]
+
+      @mutex: Thread::Mutex
+
+      @channel: String
+
+      attr_reader channel: untyped
+
+      # @rbs (?channel: String) -> void
+      def initialize: (?channel: String) -> void
+
+      # @rbs () -> bool
+      def signal: () -> bool
+
+      # @rbs (timeout: Numeric) -> bool
+      def wait: (timeout: Numeric) -> bool
+
+      # Starts listening before a caller blocks, so a notification sent between
+      # startup and the first wait is not missed.
+      # @rbs () -> bool
+      def listen: () -> bool
+
+      # @rbs () -> bool
+      def stop: () -> bool
+
+      private
+
+      attr_reader mutex: untyped
+
+      attr_reader connections: untyped
+
+      # @rbs () -> void
+      def notify_channel: () -> void
+
+      # A listening connection is dedicated and per thread. `LISTEN` is per
+      # connection, a blocking wait must not hold a connection the rest of the
+      # runtime needs, and one connection cannot serve concurrent waiters: the
+      # supervisor shares one adapter across roles, and a notification consumed
+      # by one waiter would leave the others asleep until their poll expired.
+      # @rbs () -> untyped
+      def listening_connection: () -> untyped
+
+      # @rbs () -> untyped
+      def open_listening_connection: () -> untyped
+
+      # @rbs () -> Symbol
+      def thread_key: () -> Symbol
+
+      # @rbs (untyped) -> void
+      def disconnect: (untyped) -> void
+
+      # @rbs (Numeric) -> void
+      def pace_after_failure: (Numeric) -> void
+
+      # @rbs (Symbol, Exception) -> void
+      def instrument_failure: (Symbol, Exception) -> void
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# Generated from lib/solid_objects/wake_up_adapters.rb with RBS::Inline
+
+module SolidObjects
+  module WakeUpAdapters
+    # Returns the best wake-up strategy for a connection: cross-process
+    # notifications where the database provides them, and the in-process
+    # default everywhere else.
+    #
+    # This is deliberately not the default. A notification adapter opens a
+    # connection per waiting thread outside the pool, and `LISTEN` does not
+    # survive a transaction-pooling proxy such as PgBouncer, so adopting it is
+    # a deployment decision rather than an upgrade side effect.
+    #
+    # @rbs (?untyped) -> untyped
+    def self?.for: (?untyped) -> untyped
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.8.0
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -403,6 +403,8 @@ files:
 - lib/solid_objects/turbo_stream_renderer.rb
 - lib/solid_objects/version.rb
 - lib/solid_objects/wake_up.rb
+- lib/solid_objects/wake_up_adapters.rb
+- lib/solid_objects/wake_up_adapters/postgresql.rb
 - lib/solid_objects/worker.rb
 - lib/tasks/solid_objects_tasks.rake
 - sig/generated/controllers/solid_objects/application_controller.rbs
@@ -474,6 +476,8 @@ files:
 - sig/generated/lib/solid_objects/turbo_stream_renderer.rbs
 - sig/generated/lib/solid_objects/version.rbs
 - sig/generated/lib/solid_objects/wake_up.rbs
+- sig/generated/lib/solid_objects/wake_up_adapters.rbs
+- sig/generated/lib/solid_objects/wake_up_adapters/postgresql.rbs
 - sig/generated/lib/solid_objects/worker.rbs
 - sig/generated/models/solid_objects/broadcast.rbs
 - sig/generated/models/solid_objects/claimed_message.rbs