solid_objects 0.13.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dc01a4c7b7f44d7dbd68b1194abd64a2c5515d5280a1e9cae15b119ff18508c
-  data.tar.gz: 68099ea645dff1d976f9aeda77d79d04ed8280e18bfc6d4235daca972ffafad4
+  metadata.gz: e5bd1724baaa40d79ec3693558ef7aa8e37830e4c5afd1da1d5774356d1e584e
+  data.tar.gz: 1e7a2307cae51316b9b4c4f56ea6fc986a622e3665541514137d87bbf72b2e9a
 SHA512:
-  metadata.gz: 335cec6b8f87328e9a88eee32bbd8aaca5b019cb0ef76dfa70f5efa261afb81a2a034d3bc6a11189f22c4809583d9cce1538c6ecb1ff8cc8319c1d195fec8295
-  data.tar.gz: 445c227d5badd737cb44f9b44b87917b73c3e2a55a66acb6a4cd1fe09a39febda314f00188cd35eabc70acef5d5b95503c3cedf5c35632e22948fa62667a62db
+  metadata.gz: b1b5284ef616f306bea2136d7becf4a3c8e4aa2adbcc24eb5da08c3f33e85f34551f687ff7133cd3781abba79d4f0dac919657d9150bfe3ebd021417542d505b
+  data.tar.gz: 6971c0ee78d9eab66776a5ba6d60dcc403d3346c57cffca795797f50048fc419b6473d3d620c4d025238916757f52ed79ed1ec153feaa3dda84744d740b08045

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.13.1 - 2026-08-16
+
+- Back idle actor, effect, reminder, and broadcast polling off exponentially
+  from the configured fast interval to a new one-second idle ceiling. Any
+  processed work or wake-up resets the role immediately, and actor polling
+  remains capped by the lease-renewal interval.
+- Expose each role's `current_polling_interval` and emit
+  `solid_objects.polling.interval_changed` instrumentation for every idle,
+  work, and wake-up transition.
+- Warn once when live processes share the database without a configured
+  cross-process wake-up adapter.
+- Make the in-process wake-up generation-aware so a signal committed between
+  an empty claim and the wait is not missed. PostgreSQL and Redis adapters now
+  expose the same watch contract.
+- Add a reproducible four-role SQLite idle benchmark and repair the benchmark
+  schema setup for the current operation columns.
+- **Behavior change:** `polling_interval` is now the fast interval after
+  activity, not a constant idle cadence. Existing explicit values back off to
+  `idle_polling_interval`, which defaults to one second. Set both options to
+  the same value to preserve a fixed cadence. Existing custom wake-up adapters
+  that return `nil` remain at the fast cadence until they return `false` for a
+  timeout and `true` for a notification.
+
 ## 0.13.0 - 2026-08-15
 
 - **Breaking:** make observables invalidation-only by default. An ordinary

data/README.md

@@ -1014,6 +1014,7 @@ Important defaults:
 | Setting | Default |
 | --- | ---: |
 | `polling_interval` | 0.1 seconds |
+| `idle_polling_interval` | 1 second |
 | `sync_polling_interval` | 0.05 seconds |
 | `lease_duration` | 30 seconds |
 | `lease_renewal_interval` | 10 seconds |
@@ -1038,6 +1039,14 @@ Payload, state, and result limits; retry delay; table prefix; logging; wake-up;
 broadcast; database; and authorization adapters are also configurable. Invalid
 lease intervals, component counts, and size limits fail fast at boot.
 
+`polling_interval` is the fast interval after work or a wake-up. Consecutive
+empty passes double it up to `idle_polling_interval`. Actor workers never wait
+longer than `lease_renewal_interval`. Set the fast and idle values equal for a
+fixed cadence. The default wake-up reaches only the current Ruby process;
+configure PostgreSQL notifications or optional Redis Pub/Sub when separate
+processes need low-latency delivery. The runtime warns once when it sees that
+topology without an adapter.
+
 ## Workers and operations
 
 `solid_objects start` runs actor, effect, reminder, and broadcast roles under
@@ -1299,8 +1308,8 @@ Partially implemented:
 
 - the supervisor starts and drains roles but does not replace a crashed role or
   run periodic maintenance automatically;
-- cross-process wake-up uses polling; PostgreSQL notifications and optional
-  Redis acceleration are not implemented;
+- PostgreSQL notifications and optional Redis acceleration are implemented,
+  but adapter selection remains explicit and polling is the durable fallback;
 - live observable and component replacement work, while Turbo append actions
   remain future work;
 - local admission limits exist, but distributed rate limits and global

data/benchmark/idle_polling.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "json"
+require "rbconfig"
+require_relative "support"
+
+class CountingWakeUp < SolidObjects::WakeUp
+  def initialize
+    super
+    @count_mutex = Mutex.new
+    @poll_count = 0
+  end
+
+  def wait(timeout:, generation: nil)
+    @count_mutex.synchronize { @poll_count += 1 }
+    super
+  end
+
+  def reset_count
+    @count_mutex.synchronize { @poll_count = 0 }
+  end
+
+  def poll_count
+    @count_mutex.synchronize { @poll_count }
+  end
+end
+
+def measure(interval:, warmup:, duration:, wake_up:)
+  SolidObjects.configuration.polling_interval = interval
+  SolidObjects.configuration.idle_polling_interval = 1.0
+  components = [
+    SolidObjects::Worker.new,
+    SolidObjects::EffectExecutor.new,
+    SolidObjects::ReminderScheduler.new,
+    SolidObjects::BroadcastExecutor.new
+  ]
+  threads = components.map { |component| Thread.new { component.run } }
+
+  sleep warmup
+  wake_up.reset_count
+  cpu_started_at = Process.times
+  wall_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  sleep duration
+  wall_elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - wall_started_at
+  cpu_finished_at = Process.times
+  cpu_elapsed = cpu_finished_at.utime + cpu_finished_at.stime -
+    cpu_started_at.utime - cpu_started_at.stime
+  poll_count = wake_up.poll_count
+
+  {
+    polling_interval: interval,
+    idle_polling_interval: SolidObjects.configuration.idle_polling_interval,
+    current_intervals: components.map(&:current_polling_interval),
+    polls: poll_count,
+    polls_per_second: (poll_count / wall_elapsed).round(3),
+    idle_cpu_percent: ((cpu_elapsed / wall_elapsed) * 100).round(3)
+  }
+ensure
+  components&.each(&:request_shutdown)
+  threads&.each { |thread| thread.join(2) }
+  components&.each(&:stop)
+end
+
+intervals = ENV.fetch("INTERVALS", "0.02,0.1,0.5").split(",").map do |value|
+  Float(value).tap { |interval| raise ArgumentError, "intervals must be positive" unless interval.positive? }
+end
+warmup = Float(ENV.fetch("WARMUP", "3"))
+duration = Float(ENV.fetch("DURATION", "10"))
+raise ArgumentError, "warmup must be positive" unless warmup.positive?
+raise ArgumentError, "duration must be positive" unless duration.positive?
+
+SolidObjectsBenchmark.setup
+wake_up = CountingWakeUp.new
+SolidObjects.configuration.wake_up_adapter = wake_up
+database_version = ActiveRecord::Base.connection.select_value("SELECT sqlite_version()")
+results = intervals.map { |interval| measure(interval:, warmup:, duration:, wake_up:) }
+puts JSON.pretty_generate(
+  measured_at: Time.now.utc.iso8601,
+  package_version: SolidObjects::VERSION,
+  runtime: {
+    ruby: RUBY_DESCRIPTION,
+    platform: RUBY_PLATFORM,
+    cpu: RbConfig::CONFIG.fetch("host_cpu")
+  },
+  database: {
+    adapter: "sqlite",
+    version: database_version,
+    path: SolidObjectsBenchmark::DATABASE_PATH
+  },
+  methodology: {
+    roles: %w[actors effects reminders broadcasts],
+    warmup_seconds: warmup,
+    duration_seconds: duration,
+    cpu_percent: "process user plus system CPU time divided by wall time"
+  },
+  results:
+)
+SolidObjectsBenchmark.teardown

data/benchmark/support.rb

@@ -402,8 +402,10 @@ module SolidObjectsBenchmark
     def migrate
       require_relative "../db/migrate/20260805000000_create_solid_objects_tables"
       require_relative "../db/migrate/20260806000000_add_state_revision_to_solid_objects_instances"
+      require_relative "../db/migrate/20260813000000_rename_message_dispatch_columns"
       CreateSolidObjectsTables.new.migrate(:up)
       AddStateRevisionToSolidObjectsInstances.new.migrate(:up)
+      RenameMessageDispatchColumns.new.migrate(:up)
     end
 
     # @rbs () -> void

data/docs/adr/0011-wake-up-strategy.md

@@ -11,6 +11,10 @@ Polling adds latency and database queries. PostgreSQL notifications are transact
 
 Database rows remain the only durable source of work and results. Wake-up
 adapters only prompt workers and synchronous waiters to re-query those rows.
+Actor, effect, reminder, and broadcast roles double consecutive empty waits
+from `polling_interval` to `idle_polling_interval`. Work and notifications reset
+the wait immediately. Actor workers clamp the ceiling to
+`lease_renewal_interval`.
 
 The interface supports:
 
@@ -40,4 +44,6 @@ Timeout does not cancel durable work.
 - A reconnecting PostgreSQL listener must commit `LISTEN`, inspect current state, and then wait.
 - Redis loss only increases latency and never loses durable work.
 - Every adapter retains periodic polling to close startup, reconnect, and missed-message races.
+- A process that returns `false` from a timed wait participates in backoff; an older custom adapter that returns `nil` keeps the fast cadence.
+- A multi-process deployment without an adapter trades idle database load for up to the current idle polling interval of notification latency and logs that topology once.
 - Notification payloads never contain actor arguments or results.

data/docs/architecture.md

@@ -365,8 +365,8 @@ it drains earlier messages and the target through the same activation and
 executor used by workers. If another process owns the actor, the caller waits
 for the row to become completed, rejected, dead-lettered, destroyed, or timed
 out. Every wait re-queries durable rows. The implemented wake-up interface
-provides same-process signaling, bounded polling, and dependency injection.
-PostgreSQL `LISTEN/NOTIFY` and optional Redis Pub/Sub are planned adapters.
+provides generation-aware same-process signaling, adaptive bounded polling,
+PostgreSQL `LISTEN/NOTIFY`, and optional Redis Pub/Sub.
 
 The normal path does not wait for a worker polling interval because the caller
 assists execution immediately. End-to-end latency still includes earlier

data/docs/benchmarks.md

@@ -5,6 +5,44 @@ They include the runtime's Active Record and database query overhead and will
 vary with hardware, schema size, connection pools, durability settings, and
 contention.
 
+## Idle SQLite polling
+
+Run the four-role idle harness with:
+
+```bash
+bundle exec ruby -Ilib benchmark/idle_polling.rb
+```
+
+It warms each interval for three seconds, measures for ten seconds, and reports
+process user plus system CPU time divided by wall time. Measured August 16,
+2026 on an Apple M5 with Ruby 4.0.6 and SQLite 3.53.2. The before run used
+0.13.0; the after run used the prepared 0.13.1 tree.
+
+| Fast interval | Before polls/s | Before CPU | After polls/s | After CPU |
+| ---: | ---: | ---: | ---: | ---: |
+| 20 ms | 165.340 | 8.401% | 3.998 | 0.947% |
+| 100 ms | 38.396 | 2.925% | 3.999 | 0.482% |
+| 500 ms | 7.998 | 2.061% | 3.996 | 0.283% |
+
+The after run reached the one-second ceiling for the actor, effect, reminder,
+and broadcast roles. These are developer-laptop measurements, not a CPU
+guarantee; timer scheduling, YJIT, the SQLite file, and unrelated host activity
+affect short samples.
+
+Five SQLite samples measured durable enqueue through committed completion after
+2.5 seconds of idleness. The polling-only multi-process harness submits just
+after an empty pass, so it measures approximately the full polling wait rather
+than average arrival latency.
+
+| Topology | 0.13.0 p50 | Prepared 0.13.1 p50 |
+| --- | ---: | ---: |
+| One process, in-process wake-up | 43.360 ms | 50.339 ms |
+| Two processes, polling only | 117.787 ms | 1,028.006 ms |
+
+The local wake-up keeps the one-process path prompt after backoff. The
+polling-only row is the explicit tradeoff: use PostgreSQL notifications or
+optional Redis Pub/Sub when separate processes need low-latency delivery.
+
 ## Production-shaped adoption measurement
 
 An adoption evaluation measured Solid Objects 0.2.0 from a macOS Rails process

data/docs/development.md

@@ -140,6 +140,7 @@ COUNT=500 CONCURRENCY=4 bundle exec ruby -Ilib benchmark/concurrent_actors.rb
 COUNT=100 bundle exec ruby -Ilib benchmark/sync_latency.rb
 COUNT=500 bundle exec ruby -Ilib benchmark/activation_cache.rb
 bundle exec ruby -Ilib benchmark/query_count.rb
+bundle exec ruby -Ilib benchmark/idle_polling.rb
 ```
 
 SQLite is the default. Set `SOLID_OBJECTS_DATABASE_URL` to benchmark a dedicated

data/docs/operations.md

@@ -69,6 +69,7 @@ Important controls include:
 - `lease_duration`
 - `lease_renewal_interval`
 - `polling_interval`
+- `idle_polling_interval`
 - `max_mailbox_length`
 - payload, state, and result byte limits
 - retry attempts and delay
@@ -81,6 +82,29 @@ Keep lease duration comfortably above renewal interval and expected database
 pause time. A handler can exceed the pass-duration budget because Ruby code is
 not safely preempted; alert on message duration and isolate untrusted work.
 
+## Polling and wake-up adapters
+
+`polling_interval` is the fast interval after work or a wake-up. Consecutive
+empty actor, effect, reminder, and broadcast passes double that role's wait up
+to `idle_polling_interval`, which defaults to one second. Actor workers clamp
+the ceiling to `lease_renewal_interval` while they may hold cached activations.
+Set the fast and idle values equal for a fixed cadence.
+
+The default wake-up interrupts waits only in the current Ruby process. When a
+live process record shows that the database is shared across processes and no
+adapter is configured, the runtime logs
+`solid_objects.polling_only_cross_process_wake_up` once. Configure
+`WakeUpAdapters::Postgresql` or `WakeUpAdapters::Redis` when separate processes
+need prompt delivery. Without one, newly committed work can wait up to the
+current idle polling interval.
+
+Each role exposes `current_polling_interval`.
+`solid_objects.polling.interval_changed` reports the role, reason, previous
+interval, and current interval. The polling-only warning is also emitted as
+`solid_objects.polling.only_cross_process_wake_up` instrumentation. Custom
+adapters should return `true` for a notification and `false` for a timeout; an
+older adapter that returns `nil` remains compatible and keeps the fast cadence.
+
 ## Graceful shutdown
 
 The supervisor requests shutdown, stops new claims, lets active loops return,

data/docs/roadmap.md

@@ -83,11 +83,14 @@
   What is not done is making any of them automatic. In-process signaling cannot
   cross process boundaries, so by default 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. An adapter removes that floor, measured at 103.7 ms
-  to 2.9 ms at p50 on PostgreSQL and 103.8 ms to 5.7 ms on Redis, but each stays
-  opt-in for a reason: the PostgreSQL adapter opens a connection per waiting
-  thread outside the pool and `LISTEN` does not survive a transaction-pooling
-  proxy such as PgBouncer, and Redis is not a dependency of this gem.
+  the current adaptive polling interval, up to the one-second
+  `idle_polling_interval` default. The runtime warns once when it observes this
+  topology without an adapter. An adapter removes that floor, measured before
+  adaptive polling at 103.7 ms to 2.9 ms at p50 on PostgreSQL and 103.8 ms to
+  5.7 ms on Redis, but each stays opt-in for a reason: the PostgreSQL adapter
+  opens a connection per waiting thread outside the pool and `LISTEN` does not
+  survive a transaction-pooling proxy such as PgBouncer, and Redis is not a
+  dependency of this gem.
   `WakeUpAdapters.for` selects notifications on PostgreSQL and the in-process
   default elsewhere; it never selects Redis. An application that configures
   nothing keeps polling, and MySQL applications keep polling unless they

data/lib/solid_objects/broadcast_executor.rb

@@ -1,11 +1,14 @@
 # rbs_inline: enabled
 
+require "solid_objects/polling_backoff"
+
 module SolidObjects
   class BroadcastExecutor
     # @rbs @process_registry: ProcessRegistry
     # @rbs @database_adapter: DatabaseAdapter
     # @rbs @stopped: bool
     # @rbs @shutdown_requested: bool
+    # @rbs @polling_backoff: PollingBackoff
 
     # @rbs (?process_registry: ProcessRegistry, ?database_adapter: DatabaseAdapter) -> void
     def initialize(
@@ -17,6 +20,17 @@ module SolidObjects
       process_registry.register(kind: "broadcast")
       @stopped = false
       @shutdown_requested = false
+      @polling_backoff = PollingBackoff.new(
+        minimum_interval: SolidObjects.configuration.polling_interval,
+        maximum_interval: SolidObjects.configuration.idle_polling_interval,
+        on_change: ->(transition) do
+          SolidObjects.instrument(
+            :"polling.interval_changed",
+            role: "broadcasts",
+            **transition
+          )
+        end
+      )
     end
 
     # @rbs () -> bool
@@ -46,11 +60,23 @@ module SolidObjects
 
     # @rbs () -> void
     def run
+      ProcessRegistry.warn_if_polling_is_only_cross_process_wake_up
+
       until shutdown_requested?
+        wake_up = SolidObjects.wake_up
+        watch = wake_up.respond_to?(:watch) ? wake_up.watch : wake_up
         worked = run_once
-        next if worked
-
-        SolidObjects.wake_up.wait(timeout: SolidObjects.configuration.polling_interval)
+        if worked
+          polling_backoff.reset(:work)
+          next
+        end
+
+        notified = watch.wait(timeout: current_polling_interval)
+        if notified == false
+          polling_backoff.record_idle
+        else
+          polling_backoff.reset(:wake_up)
+        end
       end
     ensure
       stop
@@ -72,9 +98,14 @@ module SolidObjects
       @shutdown_requested
     end
 
+    # @rbs () -> Float
+    def current_polling_interval
+      polling_backoff.current_interval
+    end
+
     private
 
-    attr_reader :process_registry, :database_adapter
+    attr_reader :process_registry, :database_adapter, :polling_backoff
 
     # @rbs () -> Broadcast?
     def claim_next

data/lib/solid_objects/configuration.rb

@@ -4,6 +4,7 @@ module SolidObjects
   class Configuration
     # @rbs @table_name_prefix: String
     # @rbs @polling_interval: Float
+    # @rbs @idle_polling_interval: Float
     # @rbs @sync_polling_interval: Float
     # @rbs @lease_duration: Float
     # @rbs @lease_renewal_interval: Float
@@ -49,6 +50,7 @@ module SolidObjects
 
     attr_accessor :table_name_prefix,
       :polling_interval,
+      :idle_polling_interval,
       :sync_polling_interval,
       :lease_duration,
       :lease_renewal_interval,
@@ -99,6 +101,7 @@ module SolidObjects
     def initialize
       @table_name_prefix = "solid_objects_"
       @polling_interval = 0.1
+      @idle_polling_interval = 1.0
       @sync_polling_interval = 0.05
       @lease_duration = 30.0
       @lease_renewal_interval = 10.0
@@ -241,6 +244,7 @@ module SolidObjects
     def positive_values
       {
         polling_interval:,
+        idle_polling_interval:,
         sync_polling_interval:,
         lease_duration:,
         lease_renewal_interval:,

data/lib/solid_objects/effect_executor.rb

@@ -1,5 +1,7 @@
 # rbs_inline: enabled
 
+require "solid_objects/polling_backoff"
+
 module SolidObjects
   EffectContext = Data.define(:id, :attempt, :source_message_id, :actor_type, :actor_id)
 
@@ -10,6 +12,7 @@ module SolidObjects
     # @rbs @database_adapter: DatabaseAdapter
     # @rbs @stopped: bool
     # @rbs @shutdown_requested: bool
+    # @rbs @polling_backoff: PollingBackoff
 
     # @rbs (?process_registry: ProcessRegistry, ?database_adapter: DatabaseAdapter) -> void
     def initialize(
@@ -21,6 +24,17 @@ module SolidObjects
       process_registry.register(kind: "effect")
       @stopped = false
       @shutdown_requested = false
+      @polling_backoff = PollingBackoff.new(
+        minimum_interval: SolidObjects.configuration.polling_interval,
+        maximum_interval: SolidObjects.configuration.idle_polling_interval,
+        on_change: ->(transition) do
+          SolidObjects.instrument(
+            :"polling.interval_changed",
+            role: "effects",
+            **transition
+          )
+        end
+      )
     end
 
     # @rbs () -> bool
@@ -50,11 +64,23 @@ module SolidObjects
 
     # @rbs () -> void
     def run
+      ProcessRegistry.warn_if_polling_is_only_cross_process_wake_up
+
       until shutdown_requested?
+        wake_up = SolidObjects.wake_up
+        watch = wake_up.respond_to?(:watch) ? wake_up.watch : wake_up
         worked = run_once
-        next if worked
+        if worked
+          polling_backoff.reset(:work)
+          next
+        end
 
-        SolidObjects.wake_up.wait(timeout: SolidObjects.configuration.polling_interval)
+        notified = watch.wait(timeout: current_polling_interval)
+        if notified == false
+          polling_backoff.record_idle
+        else
+          polling_backoff.reset(:wake_up)
+        end
       end
     ensure
       stop
@@ -76,9 +102,14 @@ module SolidObjects
       @shutdown_requested
     end
 
+    # @rbs () -> Float
+    def current_polling_interval
+      polling_backoff.current_interval
+    end
+
     private
 
-    attr_reader :process_registry, :database_adapter
+    attr_reader :process_registry, :database_adapter, :polling_backoff
 
     # @rbs () -> Effect?
     def claim_next

data/lib/solid_objects/polling_backoff.rb

@@ -0,0 +1,45 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class PollingBackoff
+    # @rbs @minimum_interval: Float
+    # @rbs @maximum_interval: Float
+    # @rbs @current_interval: Float
+    # @rbs @on_change: Proc?
+
+    attr_reader :current_interval
+
+    # @rbs (minimum_interval: Numeric, maximum_interval: Numeric, ?on_change: Proc?) -> void
+    def initialize(minimum_interval:, maximum_interval:, on_change: nil)
+      @minimum_interval = minimum_interval.to_f
+      @maximum_interval = [ @minimum_interval, maximum_interval.to_f ].max
+      @current_interval = @minimum_interval
+      @on_change = on_change
+    end
+
+    # @rbs () -> void
+    def record_idle
+      change([ current_interval * 2, @maximum_interval ].min, :idle)
+    end
+
+    # @rbs (:work | :wake_up) -> void
+    def reset(reason)
+      change(@minimum_interval, reason)
+    end
+
+    private
+
+    # @rbs (Float, :idle | :work | :wake_up) -> void
+    def change(interval, reason)
+      return if interval == current_interval
+
+      previous_interval = current_interval
+      @current_interval = interval
+      @on_change&.call(
+        previous_interval:,
+        current_interval: interval,
+        reason:
+      )
+    end
+  end
+end

data/lib/solid_objects/process_registry.rb

@@ -4,6 +4,9 @@ require "socket"
 
 module SolidObjects
   class ProcessRegistry
+    @polling_warning_mutex = Mutex.new
+    @polling_warning_emitted = false
+
     class << self
       # @rbs (?now: Time) -> Integer
       def cleanup_dead(now: SolidObjects.database_adapter.database_now)
@@ -53,8 +56,56 @@ module SolidObjects
         true
       end
 
+      # @rbs () -> void
+      def warn_if_polling_is_only_cross_process_wake_up
+        return if SolidObjects.configuration.wake_up_adapter
+
+        polling_warning_mutex.synchronize do
+          return if polling_warning_emitted?
+          return unless another_live_process?
+
+          payload = {
+            event: "solid_objects.polling_only_cross_process_wake_up",
+            polling_interval: SolidObjects.configuration.polling_interval,
+            idle_polling_interval: SolidObjects.configuration.idle_polling_interval
+          }
+          SolidObjects.configuration.logger.warn(payload)
+          SolidObjects.instrument(
+            :"polling.only_cross_process_wake_up",
+            **payload.except(:event)
+          )
+          @polling_warning_emitted = true
+        end
+      end
+
+      # @rbs () -> void
+      def reset_polling_warning!
+        polling_warning_mutex.synchronize { @polling_warning_emitted = false }
+      end
+
       private
 
+      # @rbs () -> bool
+      def another_live_process?
+        alive_after = SolidObjects.database_adapter.database_now -
+          SolidObjects.configuration.process_alive_threshold
+        Process
+          .where.not(shutdown_state: "stopped")
+          .where(last_heartbeat_at: alive_after..)
+          .where("hostname <> ? OR pid <> ?", Socket.gethostname, ::Process.pid)
+          .exists?
+      end
+
+      # @rbs () -> bool
+      def polling_warning_emitted?
+        @polling_warning_emitted
+      end
+
+      # @rbs () -> Mutex
+      def polling_warning_mutex
+        @polling_warning_mutex ||= Mutex.new
+      end
+
       # @rbs (Process, Time) -> void
       def cleanup_process(process_record, now)
         deregister(process_record, now:)

data/lib/solid_objects/reminder_scheduler.rb

@@ -1,11 +1,14 @@
 # rbs_inline: enabled
 
+require "solid_objects/polling_backoff"
+
 module SolidObjects
   class ReminderScheduler
     # @rbs @process_registry: ProcessRegistry
     # @rbs @database_adapter: DatabaseAdapter
     # @rbs @stopped: bool
     # @rbs @shutdown_requested: bool
+    # @rbs @polling_backoff: PollingBackoff
 
     # @rbs (?process_registry: ProcessRegistry, ?database_adapter: DatabaseAdapter) -> void
     def initialize(
@@ -17,6 +20,17 @@ module SolidObjects
       process_registry.register(kind: "reminder")
       @stopped = false
       @shutdown_requested = false
+      @polling_backoff = PollingBackoff.new(
+        minimum_interval: SolidObjects.configuration.polling_interval,
+        maximum_interval: SolidObjects.configuration.idle_polling_interval,
+        on_change: ->(transition) do
+          SolidObjects.instrument(
+            :"polling.interval_changed",
+            role: "reminders",
+            **transition
+          )
+        end
+      )
     end
 
     # @rbs (?now: Time?) -> bool
@@ -45,11 +59,23 @@ module SolidObjects
 
     # @rbs () -> void
     def run
+      ProcessRegistry.warn_if_polling_is_only_cross_process_wake_up
+
       until shutdown_requested?
+        wake_up = SolidObjects.wake_up
+        watch = wake_up.respond_to?(:watch) ? wake_up.watch : wake_up
         worked = run_once
-        next if worked
-
-        SolidObjects.wake_up.wait(timeout: SolidObjects.configuration.polling_interval)
+        if worked
+          polling_backoff.reset(:work)
+          next
+        end
+
+        notified = watch.wait(timeout: current_polling_interval)
+        if notified == false
+          polling_backoff.record_idle
+        else
+          polling_backoff.reset(:wake_up)
+        end
       end
     ensure
       stop
@@ -71,9 +97,14 @@ module SolidObjects
       @shutdown_requested
     end
 
+    # @rbs () -> Float
+    def current_polling_interval
+      polling_backoff.current_interval
+    end
+
     private
 
-    attr_reader :process_registry, :database_adapter
+    attr_reader :process_registry, :database_adapter, :polling_backoff
 
     # @rbs (now: Time?) -> Reminder?
     def claim_next(now:)

data/lib/solid_objects/version.rb

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

data/lib/solid_objects/wake_up.rb

@@ -2,23 +2,55 @@
 
 module SolidObjects
   class WakeUp
+    class Watch
+      # @rbs @wake_up: WakeUp
+      # @rbs @generation: Integer
+
+      # @rbs (WakeUp, Integer) -> void
+      def initialize(wake_up, generation)
+        @wake_up = wake_up
+        @generation = generation
+      end
+
+      # @rbs (timeout: Numeric) -> bool
+      def wait(timeout:)
+        @wake_up.wait(timeout:, generation: @generation)
+      end
+    end
+
     # @rbs @mutex: Mutex
     # @rbs @condition: Thread::ConditionVariable
+    # @rbs @generation: Integer
 
     # @rbs () -> void
     def initialize
       @mutex = Mutex.new
       @condition = Thread::ConditionVariable.new
+      @generation = 0
     end
 
     # @rbs () -> void
     def signal
-      mutex.synchronize { condition.broadcast }
+      mutex.synchronize do
+        @generation += 1
+        condition.broadcast
+      end
     end
 
-    # @rbs (timeout: Numeric) -> void
-    def wait(timeout:)
-      mutex.synchronize { condition.wait(mutex, timeout) }
+    # @rbs () -> Watch
+    def watch
+      mutex.synchronize { Watch.new(self, @generation) }
+    end
+
+    # @rbs (timeout: Numeric, ?generation: Integer?) -> bool
+    def wait(timeout:, generation: nil)
+      mutex.synchronize do
+        return true if generation && @generation != generation
+
+        generation ||= @generation
+        condition.wait(mutex, timeout)
+        @generation != generation
+      end
     end
 
     private

data/lib/solid_objects/wake_up_adapters/postgresql.rb

@@ -45,6 +45,12 @@ module SolidObjects
         false
       end
 
+      # @rbs () -> self
+      def watch
+        listen
+        self
+      end
+
       # Starts listening before a caller blocks, so a notification sent between
       # startup and the first wait is not missed.
       # @rbs () -> bool

data/lib/solid_objects/wake_up_adapters/redis.rb

@@ -12,6 +12,22 @@ module SolidObjects
     # polling interval remains the upper bound, so a missed or failed
     # notification costs latency rather than correctness.
     class Redis
+      class Watch
+        # @rbs @adapter: Redis
+        # @rbs @generation: Integer
+
+        # @rbs (Redis, Integer) -> void
+        def initialize(adapter, generation)
+          @adapter = adapter
+          @generation = generation
+        end
+
+        # @rbs (timeout: Numeric) -> bool
+        def wait(timeout:)
+          @adapter.wait(timeout:, generation: @generation)
+        end
+      end
+
       CHANNEL = "solid_objects_wake_up"
       FAILED_WAIT_INTERVAL = 0.05
       SUBSCRIBE_TIMEOUT = 5.0
@@ -52,9 +68,9 @@ module SolidObjects
       # The counter is snapshotted before subscribing, and re-checked before
       # blocking, so a signal delivered while this caller was still getting
       # ready is observed rather than absorbed into the new baseline.
-      # @rbs (timeout: Numeric) -> bool
-      def wait(timeout:)
-        signalled = mutex.synchronize { @signalled }
+      # @rbs (timeout: Numeric, ?generation: Integer?) -> bool
+      def wait(timeout:, generation: nil)
+        signalled = generation || mutex.synchronize { @signalled }
         return paced_failure(timeout) unless listen
 
         mutex.synchronize do
@@ -65,6 +81,12 @@ module SolidObjects
         end
       end
 
+      # @rbs () -> Watch
+      def watch
+        listen
+        mutex.synchronize { Watch.new(self, @signalled) }
+      end
+
       # Redis delivers to a subscribed connection only, and a subscribed
       # connection cannot serve other callers, so one background subscription
       # per process fans out to every waiting role in memory. Subscribing

data/lib/solid_objects/worker.rb

@@ -5,6 +5,7 @@ require "solid_objects/activation_manager"
 require "solid_objects/activation"
 require "solid_objects/executor"
 require "solid_objects/lease_renewer"
+require "solid_objects/polling_backoff"
 
 module SolidObjects
   class Worker
@@ -13,6 +14,7 @@ module SolidObjects
     # @rbs @activations: Hash[Integer, Activation]
     # @rbs @stopped: bool
     # @rbs @shutdown_requested: bool
+    # @rbs @polling_backoff: PollingBackoff
 
     # @rbs (?process_registry: ProcessRegistry) -> void
     def initialize(process_registry: ProcessRegistry.new)
@@ -22,6 +24,23 @@ module SolidObjects
       @activations = {}
       @stopped = false
       @shutdown_requested = false
+      @polling_backoff = PollingBackoff.new(
+        minimum_interval: [
+          SolidObjects.configuration.polling_interval,
+          SolidObjects.configuration.lease_renewal_interval
+        ].min,
+        maximum_interval: [
+          SolidObjects.configuration.idle_polling_interval,
+          SolidObjects.configuration.lease_renewal_interval
+        ].min,
+        on_change: ->(transition) do
+          SolidObjects.instrument(
+            :"polling.interval_changed",
+            role: "actors",
+            **transition
+          )
+        end
+      )
     end
 
     # @rbs () -> Integer
@@ -70,11 +89,23 @@ module SolidObjects
 
     # @rbs () -> void
     def run
+      ProcessRegistry.warn_if_polling_is_only_cross_process_wake_up
+
       until shutdown_requested?
+        wake_up = SolidObjects.wake_up
+        watch = wake_up.respond_to?(:watch) ? wake_up.watch : wake_up
         processed = run_once
-        next if processed.positive?
+        if processed.positive?
+          polling_backoff.reset(:work)
+          next
+        end
 
-        SolidObjects.wake_up.wait(timeout: SolidObjects.configuration.polling_interval)
+        notified = watch.wait(timeout: current_polling_interval)
+        if notified == false
+          polling_backoff.record_idle
+        else
+          polling_backoff.reset(:wake_up)
+        end
       end
     ensure
       stop
@@ -107,9 +138,14 @@ module SolidObjects
       @shutdown_requested
     end
 
+    # @rbs () -> Float
+    def current_polling_interval
+      polling_backoff.current_interval
+    end
+
     private
 
-    attr_reader :process_registry, :activation_manager, :activations
+    attr_reader :process_registry, :activation_manager, :activations, :polling_backoff
 
     # @rbs () -> Activation?
     def cached_ready_activation

data/lib/solid_objects.rb

@@ -52,6 +52,7 @@ require "solid_objects/wake_up"
 require "solid_objects/wake_up_adapters/postgresql"
 require "solid_objects/wake_up_adapters/redis"
 require "solid_objects/wake_up_adapters"
+require "solid_objects/polling_backoff"
 require "solid_objects/effect_registry"
 require "solid_objects/commit_action_registry"
 require "solid_objects/lease"
@@ -153,6 +154,7 @@ module SolidObjects
 
     # @rbs () -> void
     def reset!
+      ProcessRegistry.reset_polling_warning! if defined?(ProcessRegistry)
       @configuration = Configuration.new
       @registry = ActorRegistry.new
       @client = nil

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

@@ -2,6 +2,8 @@
 
 module SolidObjects
   class BroadcastExecutor
+    @polling_backoff: PollingBackoff
+
     @shutdown_requested: bool
 
     @stopped: bool
@@ -31,12 +33,17 @@ module SolidObjects
     # @rbs () -> bool
     def shutdown_requested?: () -> bool
 
+    # @rbs () -> Float
+    def current_polling_interval: () -> Float
+
     private
 
     attr_reader process_registry: untyped
 
     attr_reader database_adapter: untyped
 
+    attr_reader polling_backoff: untyped
+
     # @rbs () -> Broadcast?
     def claim_next: () -> Broadcast?
 

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

@@ -2,6 +2,8 @@
 
 module SolidObjects
   class Configuration
+    @table_name_prefix: String
+
     @process_alive_threshold: Float
 
     @shutdown_timeout: Float
@@ -56,10 +58,10 @@ module SolidObjects
 
     @authorize_administration: Proc
 
-    @table_name_prefix: String
-
     @polling_interval: Float
 
+    @idle_polling_interval: Float
+
     @sync_polling_interval: Float
 
     @lease_duration: Float
@@ -94,6 +96,8 @@ module SolidObjects
 
     attr_accessor polling_interval: untyped
 
+    attr_accessor idle_polling_interval: untyped
+
     attr_accessor sync_polling_interval: untyped
 
     attr_accessor lease_duration: untyped

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

@@ -23,6 +23,8 @@ module SolidObjects
   class EffectExecutor
     ACTOR_MESSAGE_EFFECT: ::String
 
+    @polling_backoff: PollingBackoff
+
     @shutdown_requested: bool
 
     @stopped: bool
@@ -52,12 +54,17 @@ module SolidObjects
     # @rbs () -> bool
     def shutdown_requested?: () -> bool
 
+    # @rbs () -> Float
+    def current_polling_interval: () -> Float
+
     private
 
     attr_reader process_registry: untyped
 
     attr_reader database_adapter: untyped
 
+    attr_reader polling_backoff: untyped
+
     # @rbs () -> Effect?
     def claim_next: () -> Effect?
 

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

@@ -0,0 +1,29 @@
+# Generated from lib/solid_objects/polling_backoff.rb with RBS::Inline
+
+module SolidObjects
+  class PollingBackoff
+    @minimum_interval: Float
+
+    @maximum_interval: Float
+
+    @current_interval: Float
+
+    @on_change: Proc?
+
+    attr_reader current_interval: untyped
+
+    # @rbs (minimum_interval: Numeric, maximum_interval: Numeric, ?on_change: Proc?) -> void
+    def initialize: (minimum_interval: Numeric, maximum_interval: Numeric, ?on_change: Proc?) -> void
+
+    # @rbs () -> void
+    def record_idle: () -> void
+
+    # @rbs (:work | :wake_up) -> void
+    def reset: (:work | :wake_up) -> void
+
+    private
+
+    # @rbs (Float, :idle | :work | :wake_up) -> void
+    def change: (Float, :idle | :work | :wake_up) -> void
+  end
+end

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

@@ -8,6 +8,21 @@ module SolidObjects
     # @rbs (Process, ?now: Time) -> bool
     def self.deregister: (Process, ?now: Time) -> bool
 
+    # @rbs () -> void
+    def self.warn_if_polling_is_only_cross_process_wake_up: () -> void
+
+    # @rbs () -> void
+    def self.reset_polling_warning!: () -> void
+
+    # @rbs () -> bool
+    private def self.another_live_process?: () -> bool
+
+    # @rbs () -> bool
+    private def self.polling_warning_emitted?: () -> bool
+
+    # @rbs () -> Mutex
+    private def self.polling_warning_mutex: () -> Mutex
+
     # @rbs (Process, Time) -> void
     private def self.cleanup_process: (Process, Time) -> void
 

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

@@ -2,6 +2,8 @@
 
 module SolidObjects
   class ReminderScheduler
+    @polling_backoff: PollingBackoff
+
     @shutdown_requested: bool
 
     @stopped: bool
@@ -31,12 +33,17 @@ module SolidObjects
     # @rbs () -> bool
     def shutdown_requested?: () -> bool
 
+    # @rbs () -> Float
+    def current_polling_interval: () -> Float
+
     private
 
     attr_reader process_registry: untyped
 
     attr_reader database_adapter: untyped
 
+    attr_reader polling_backoff: untyped
+
     # @rbs (now: Time?) -> Reminder?
     def claim_next: (now: Time?) -> Reminder?
 

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

@@ -2,18 +2,35 @@
 
 module SolidObjects
   class WakeUp
+    class Watch
+      @wake_up: WakeUp
+
+      @generation: Integer
+
+      # @rbs (WakeUp, Integer) -> void
+      def initialize: (WakeUp, Integer) -> void
+
+      # @rbs (timeout: Numeric) -> bool
+      def wait: (timeout: Numeric) -> bool
+    end
+
     @mutex: Mutex
 
     @condition: Thread::ConditionVariable
 
+    @generation: Integer
+
     # @rbs () -> void
     def initialize: () -> void
 
     # @rbs () -> void
     def signal: () -> void
 
-    # @rbs (timeout: Numeric) -> void
-    def wait: (timeout: Numeric) -> void
+    # @rbs () -> Watch
+    def watch: () -> Watch
+
+    # @rbs (timeout: Numeric, ?generation: Integer?) -> bool
+    def wait: (timeout: Numeric, ?generation: Integer?) -> bool
 
     private
 

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

@@ -31,6 +31,9 @@ module SolidObjects
       # @rbs (timeout: Numeric) -> bool
       def wait: (timeout: Numeric) -> bool
 
+      # @rbs () -> self
+      def watch: () -> self
+
       # Starts listening before a caller blocks, so a notification sent between
       # startup and the first wait is not missed.
       # @rbs () -> bool

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

@@ -10,6 +10,18 @@ module SolidObjects
     # polling interval remains the upper bound, so a missed or failed
     # notification costs latency rather than correctness.
     class Redis
+      class Watch
+        @adapter: Redis
+
+        @generation: Integer
+
+        # @rbs (Redis, Integer) -> void
+        def initialize: (Redis, Integer) -> void
+
+        # @rbs (timeout: Numeric) -> bool
+        def wait: (timeout: Numeric) -> bool
+      end
+
       CHANNEL: ::String
 
       FAILED_WAIT_INTERVAL: ::Float
@@ -43,8 +55,11 @@ module SolidObjects
       # The counter is snapshotted before subscribing, and re-checked before
       # blocking, so a signal delivered while this caller was still getting
       # ready is observed rather than absorbed into the new baseline.
-      # @rbs (timeout: Numeric) -> bool
-      def wait: (timeout: Numeric) -> bool
+      # @rbs (timeout: Numeric, ?generation: Integer?) -> bool
+      def wait: (timeout: Numeric, ?generation: Integer?) -> bool
+
+      # @rbs () -> Watch
+      def watch: () -> Watch
 
       # Redis delivers to a subscribed connection only, and a subscribed
       # connection cannot serve other callers, so one background subscription

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

@@ -2,6 +2,8 @@
 
 module SolidObjects
   class Worker
+    @polling_backoff: PollingBackoff
+
     @shutdown_requested: bool
 
     @stopped: bool
@@ -36,6 +38,9 @@ module SolidObjects
     # @rbs () -> bool
     def shutdown_requested?: () -> bool
 
+    # @rbs () -> Float
+    def current_polling_interval: () -> Float
+
     private
 
     attr_reader process_registry: untyped
@@ -44,6 +49,8 @@ module SolidObjects
 
     attr_reader activations: untyped
 
+    attr_reader polling_backoff: untyped
+
     # @rbs () -> Activation?
     def cached_ready_activation: () -> Activation?
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.13.1
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-15 00:00:00.000000000 Z
+date: 2026-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -319,6 +319,7 @@ files:
 - benchmark/concurrent_actors.rb
 - benchmark/enqueue.rb
 - benchmark/hot_actor.rb
+- benchmark/idle_polling.rb
 - benchmark/processing.rb
 - benchmark/query_count.rb
 - benchmark/support.rb
@@ -419,6 +420,7 @@ files:
 - lib/solid_objects/message_reference.rb
 - lib/solid_objects/operation_dispatcher.rb
 - lib/solid_objects/payload_broadcast.rb
+- lib/solid_objects/polling_backoff.rb
 - lib/solid_objects/process_pruner.rb
 - lib/solid_objects/process_registry.rb
 - lib/solid_objects/reference.rb
@@ -504,6 +506,7 @@ files:
 - sig/generated/lib/solid_objects/message_reference.rbs
 - sig/generated/lib/solid_objects/operation_dispatcher.rbs
 - sig/generated/lib/solid_objects/payload_broadcast.rbs
+- sig/generated/lib/solid_objects/polling_backoff.rbs
 - sig/generated/lib/solid_objects/process_pruner.rbs
 - sig/generated/lib/solid_objects/process_registry.rbs
 - sig/generated/lib/solid_objects/reference.rbs