solid_objects 0.13.0 → 0.13.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dc01a4c7b7f44d7dbd68b1194abd64a2c5515d5280a1e9cae15b119ff18508c
-  data.tar.gz: 68099ea645dff1d976f9aeda77d79d04ed8280e18bfc6d4235daca972ffafad4
+  metadata.gz: c1043a832a75d5e7d2c9e59b332c3c6bce85a322204fdc2a056dc5198018d34d
+  data.tar.gz: 4b1505d23bab1aeb57dc722a8a613fd3c39911d2756e24c37714466e4c821b22
 SHA512:
-  metadata.gz: 335cec6b8f87328e9a88eee32bbd8aaca5b019cb0ef76dfa70f5efa261afb81a2a034d3bc6a11189f22c4809583d9cce1538c6ecb1ff8cc8319c1d195fec8295
-  data.tar.gz: 445c227d5badd737cb44f9b44b87917b73c3e2a55a66acb6a4cd1fe09a39febda314f00188cd35eabc70acef5d5b95503c3cedf5c35632e22948fa62667a62db
+  metadata.gz: 2d7c216e135b8e34c19b9130a0fcad0df6246191ee097f9a560497d0dacc47fc480e549c1ddd6ab2bc6fe9bc513245236aa47cc1650a08906a04367d0e6bd008
+  data.tar.gz: d1dc2001e0b43a2df5eb24c5cd79c6e1df99b2d6c46c90146a349dd09a557db9dcdaa7c51e51a47f5db1667b364c2dfe64d5ba73fe877248a0143e022045c764

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.13.2 - 2026-08-17
+
+- Accept a `key:` on `schedule`, naming a reminder for the item it is waiting
+  on rather than for its operation, so one actor can hold an alarm per queued
+  item. Scheduling the same key again moves that item's alarm and leaves the
+  others alone. Without a key the name is still the operation, so existing
+  reminders keep their names and their coalescing behaviour. A reminder
+  operation may no longer hold the colon that separates a key, which keeps
+  keyed and unkeyed names disjoint, and the length is checked on the composed
+  name rather than the key alone.
+- Add an authorized `SolidObjects.administration.processes` query for
+  inspecting live and stale process rows through the runtime database adapter.
+- Document rolling-deployment overlap as a reason for the polling-only warning.
+
+## 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

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/cardmagic/solid_objects/actions/workflows/ci.yml/badge.svg)](https://github.com/cardmagic/solid_objects/actions/workflows/ci.yml)
 
-**Cloudflare Durable Objects, ported to Rails.**
+**Self-hosted, distributed Durable Objects in Rails without a daemon using your existing SQL database.**
 
 Solid Objects brings the Durable Objects programming model—addressable objects,
 durable state, serialized turns, alarms, and live clients—to ordinary Rails
@@ -891,7 +891,7 @@ database enforces this with a unique index on `(instance_id, name)`.
 
 This is the same model as Orleans reminders and Durable Objects alarms, and it
 is what makes a reminder safe to re-arm from a handler that may run more than
-once. It also means this is a data-loss bug:
+once. Without a key the name is the operation, so this is a data-loss bug:
 
 ```ruby
 # Wrong. Every entry overwrites the previous entry's alarm.
@@ -904,8 +904,38 @@ end
 Two entries leave one reminder. The earlier wake-up never happens, nothing
 raises, and nothing is logged except a `solid_objects.reminder.replaced` event.
 
-Arm one alarm for the earliest item instead, and let the handler drain
-everything now due before arming the next:
+### An alarm per item, with `key:`
+
+Pass `key:` when an actor is waiting on several things at once. The key is your
+own identifier for the item, and it names that item's alarm, so each item gets
+one:
+
+```ruby
+def add(entry:)
+  self.entries = entries + [ entry ]
+  schedule(at: entry.fetch("wait_until"), key: entry.fetch("id")).deliver
+end
+```
+
+Two entries now leave two reminders. Scheduling the same key again moves that
+item's alarm and leaves the others alone, which is what makes a keyed reminder
+as safe to re-arm as an unkeyed one. The operation still decides which handler
+runs; the key only decides which alarm is which.
+
+A key must be non-empty, and the name it becomes must fit the 191-character
+column, which is checked on the composed name rather than the key alone so a
+long operation and a short key are caught too.
+
+The key is separated from the operation by a colon, so an operation may not hold
+one. Otherwise an unkeyed `deliver:item` and a `deliver` keyed `item` would be
+one name, and the second would silently take the first one's alarm. A key may
+hold colons of its own, because the operation before the first one cannot.
+
+### One alarm for a whole queue
+
+A key per item is not always what you want. An actor that only ever needs to
+know "what is next" can keep one alarm and let the handler drain everything now
+due before arming the next:
 
 ```ruby
 def add(entry:)
@@ -931,10 +961,10 @@ def arm_next
 end
 ```
 
-`deliver` drains every due item rather than one, so a single alarm serves a
-whole queue and a missed or coalesced occurrence cannot strand an entry. Use a
-distinct reminder name only when you genuinely need two independent alarms on
-one actor, such as `:deliver` and `:sweep`.
+That costs one reminder row instead of one per item, and a coalesced occurrence
+cannot strand an entry because the handler drains by time rather than by alarm.
+Prefer it when the queue is large and the items are interchangeable; prefer
+`key:` when an item needs its own alarm that can be moved on its own.
 
 Solid Objects has no `unschedule`. A reminder stops when its handler does not
 re-arm it, and destroying an actor removes its reminders.
@@ -1014,6 +1044,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 +1069,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 +1338,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,37 @@ 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.
+
+The warning excludes process rows with the current hostname and PID. It can
+therefore appear during a rolling deployment or restart overlap when an older
+and newer process briefly share the database. A process that stopped without
+graceful cleanup remains live until its heartbeat exceeds
+`process_alive_threshold`; inspect `SolidObjects.administration.processes` to
+distinguish a live overlap from a stale row without opening a second SQLite
+connection.
+
+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/actor.rb

@@ -4,7 +4,11 @@ module SolidObjects
   class Actor
     EffectIntent = Data.define(:name, :arguments, :success_operation, :failure_operation)
     CommitActionIntent = Data.define(:name, :arguments)
-    ReminderIntent = Data.define(:name, :at, :arguments, :interval_seconds, :missed_policy)
+    # The reminders table holds a name in 191 characters.
+    REMINDER_NAME_LIMIT = 191
+    REMINDER_KEY_SEPARATOR = ":"
+
+    ReminderIntent = Data.define(:name, :operation, :at, :arguments, :interval_seconds, :missed_policy)
     OutboundMessageIntent = Data.define(:actor_type, :actor_id, :operation, :arguments, :available_at, :idempotency_key)
 
     class << self
@@ -197,8 +201,13 @@ module SolidObjects
       nil
     end
 
-    # @rbs (at: Time, ?every: Numeric?, ?missed: Symbol | String) -> OperationDispatcher
-    def schedule(at:, every: nil, missed: :latest)
+    # A reminder is identified by its name, and without a key that name is the
+    # operation, so one actor holds one alarm per operation. A key gives an actor
+    # an alarm per item it is waiting on, which is what an actor holding a queue
+    # of scheduled work needs; the key is the caller's own identifier for the
+    # item, and scheduling the same key again moves that item's alarm.
+    # @rbs (at: Time, ?every: Numeric?, ?missed: Symbol | String, ?key: (String | Symbol | Integer)?) -> OperationDispatcher
+    def schedule(at:, every: nil, missed: :latest, key: nil)
       interval_seconds = every&.to_f
       if interval_seconds && !interval_seconds.positive?
         raise ArgumentError, "reminder interval must be positive"
@@ -207,13 +216,15 @@ module SolidObjects
       unless %w[all latest].include?(missed_policy)
         raise ArgumentError, "missed reminder policy must be all or latest"
       end
+      reminder_key = validated_reminder_key(key)
 
       OperationDispatcher.new(
         actor_type: self.class.actor_type,
         handlers: self.class.definition.messages
       ) do |operation, arguments|
         ReminderIntent.new(
-          name: operation.to_s,
+          name: reminder_name(operation:, key: reminder_key),
+          operation: operation.to_s,
           at:,
           arguments: Serialization.dump(arguments),
           interval_seconds:,
@@ -225,6 +236,45 @@ module SolidObjects
       end
     end
 
+    # @rbs ((String | Symbol | Integer)?) -> String?
+    def validated_reminder_key(key)
+      return nil if key.nil?
+
+      reminder_key = key.to_s
+      raise ArgumentError, "reminder key must not be empty" if reminder_key.empty?
+
+      reminder_key
+    end
+
+    # A keyed name is the operation, a colon, and the key, so an operation
+    # holding a colon of its own would make two different schedules produce one
+    # name: an unkeyed "deliver:item" and a "deliver" keyed "item" would share a
+    # row, and the second would silently take the first one's alarm. Refusing a
+    # colon in the operation keeps unkeyed names free of colons, which leaves
+    # the two kinds of name disjoint and lets a key hold colons of its own.
+    #
+    # The length is checked on the composed name rather than the key alone,
+    # because a long operation and a short key can exceed the column just as
+    # easily as the reverse. Both are refused here rather than at the insert,
+    # once the turn is already doing work.
+    # @rbs (operation: Symbol | String, key: String?) -> String
+    def reminder_name(operation:, key:)
+      operation_name = operation.to_s
+      if operation_name.include?(REMINDER_KEY_SEPARATOR)
+        raise ArgumentError,
+          "reminder operation #{operation_name.inspect} must not contain #{REMINDER_KEY_SEPARATOR.inspect}"
+      end
+      return operation_name if key.nil?
+
+      name = "#{operation_name}#{REMINDER_KEY_SEPARATOR}#{key}"
+      if name.length > REMINDER_NAME_LIMIT
+        raise ArgumentError,
+          "reminder name #{name.length} characters exceeds the #{REMINDER_NAME_LIMIT} the database holds"
+      end
+
+      name
+    end
+
     # @rbs (Reference, ?available_at: Time?, ?idempotency_key: String?) -> OperationDispatcher
     def send_to(reference, available_at: nil, idempotency_key: nil)
       actor_class = SolidObjects.registry.fetch(reference.actor_type)

data/lib/solid_objects/administration.rb

@@ -0,0 +1,44 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Administration
+    # @rbs (?authorization_context: untyped) -> Array[Hash[Symbol, untyped]]
+    def processes(authorization_context: nil)
+      authorize!(authorization_context:)
+      now = SolidObjects.database_adapter.database_now
+      stale_at = now - SolidObjects.configuration.process_alive_threshold
+
+      Process.order(:kind, :started_at).map do |process_record|
+        {
+          id: process_record.id,
+          kind: process_record.kind,
+          hostname: process_record.hostname,
+          pid: process_record.pid,
+          metadata: Serialization.readonly_copy(process_record.metadata),
+          shutdown_state: process_record.shutdown_state,
+          shutdown_requested_at: process_record.shutdown_requested_at,
+          started_at: process_record.started_at,
+          last_heartbeat_at: process_record.last_heartbeat_at,
+          stopped_at: process_record.stopped_at,
+          stale: process_record.shutdown_state != "stopped" &&
+            process_record.last_heartbeat_at <= stale_at
+        }.freeze
+      end.freeze
+    end
+
+    private
+
+    # @rbs (?authorization_context: untyped) -> void
+    def authorize!(authorization_context: nil)
+      authorized = SolidObjects.configuration.authorize_administration.call(
+        action: :inspect,
+        resource: "processes",
+        resource_id: nil,
+        authorization_context:
+      )
+      return if authorized
+
+      raise Unauthorized, "actor administration is not authorized"
+    end
+  end
+end

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