solid_objects 0.12.1 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e89f40dd095ec1d8934ff47872f3638ca441203186a7a1562dc9f603c939150
-  data.tar.gz: 23389e8737fcbfc816ca41aedf56f4b83baa6769fc2c54f6d9ca3622c67ca135
+  metadata.gz: e5bd1724baaa40d79ec3693558ef7aa8e37830e4c5afd1da1d5774356d1e584e
+  data.tar.gz: 1e7a2307cae51316b9b4c4f56ea6fc986a622e3665541514137d87bbf72b2e9a
 SHA512:
-  metadata.gz: d28e8e826c045dc546a13eb34631c692281b82b10a55205f0f6b3a17b77a1a2144bbfb786c69c86d701d42d356c65da4c26d7dd2f25a5538f9743e4405aa53b1
-  data.tar.gz: 34c89447e1592ea056d511db1fbf01de898c1563c34616a7b80058b0c1bb649b3a4e01cf7f1fad6de35bedc82e484c0a8c96b21aa0be1d959b94c3492fd3d3c4
+  metadata.gz: b1b5284ef616f306bea2136d7becf4a3c8e4aa2adbcc24eb5da08c3f33e85f34551f687ff7133cd3781abba79d4f0dac919657d9150bfe3ebd021417542d505b
+  data.tar.gz: 6971c0ee78d9eab66776a5ba6d60dcc403d3346c57cffca795797f50048fc419b6473d3d620c4d025238916757f52ed79ed1ec153feaa3dda84744d740b08045

data/CHANGELOG.md

@@ -1,5 +1,65 @@
 # 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
+  `observable :status` continues to detect changes and refresh reactive
+  components, but persists `{}` and sends no scalar value over Action Cable.
+  Declare `observable :status, broadcast: :value` to deliberately store and
+  share the projection with every authorized actor subscriber. Applications
+  upgrading from 0.12.x must add that opt-in to observables rendered as scalar
+  targets.
+- Add `SolidObjects::Web`, a mountable Rack dashboard for the actor runtime.
+  It covers instances and their committed state, the ready and claimed
+  mailbox, reminders, effects, broadcasts, dead letters, and processes, with
+  actor-type and actor-id filtering, status filters, paging, and a polled
+  `GET /stats` endpoint. Mount it with
+  `mount SolidObjects::Web => "/solid_objects/dashboard"` after
+  `require "solid_objects/web"`; requiring the gem does not load it, so a
+  worker process carries no web stack.
+- Authorize every dashboard route through `authorize_administration`. Each
+  route declares its own `action` and `resource`, and a route declared without
+  a policy raises at load time. The policy receives a context that answers
+  `request`, `session`, and `env`.
+- Add two dashboard actions: an idempotent dead letter retry through
+  `SolidObjects.dead_letters.retry`, and instance pause/resume, which sets and
+  clears `paused_at` so the activation manager stops claiming that identity. A
+  retry the mailbox refuses, such as an actor class that no longer exists,
+  renders the reason with a 422 rather than failing the request.
+- Draw instances per actor type, mailbox depth, and outbox and reminder status
+  with Chart.js, loaded from a CDN with a subresource integrity hash. The CDN
+  host is the only external origin the content security policy names. Point
+  `SolidObjects::Web.chart_library_url` at a vendored copy for a deployment
+  with no outbound network access, or set it to nil to render without charts.
+- Add `SolidObjects::Web.register` for extension tabs, routes, and view
+  directories, and `SolidObjects::Web.use` for Rack middleware in front of the
+  dashboard.
+- Add `rack` as an explicit dependency at `>= 3.1`, and package the `web/`
+  directory in the gem.
+
 ## 0.12.1 - 2026-08-13
 
 - Add invalidation-only observables with `broadcast: :invalidation`. They still

data/README.md

@@ -86,6 +86,7 @@ tested, but the project does not yet claim production readiness. See
 - [State migrations](#state-migrations)
 - [Configuration](#configuration)
 - [Workers and operations](#workers-and-operations)
+- [Dashboard](#dashboard)
 - [Database support](#database-support)
 - [Guarantees](#guarantees)
 - [When to use it](#when-to-use-it)
@@ -178,7 +179,7 @@ class ChatRoom < SolidObjects::Actor
   attribute :recent_messages, default: -> { [] }
   attribute :status, default: "open"
 
-  observable :message_count do
+  observable :message_count, broadcast: :value do
     recent_messages.length
   end
 
@@ -205,20 +206,22 @@ dependencies changes:
 <% end %>
 ```
 
-An observable's value is shared with every authorized subscriber by default
-and is stored in `solid_objects_broadcasts`. Use an invalidation-only observable
-for component dependencies whose value is private or subscriber-specific:
+Observables are invalidation-only by default. Their values remain available to
+authorized component rendering, while durable rows and Action Cable frames
+carry only change metadata. Explicitly opt a scalar observable into sharing its
+value with every authorized actor subscriber:
 
 ```ruby
-observable :player_one, broadcast: :invalidation do
-  player_in_seat(1)
+observable :message_count, broadcast: :value do
+  recent_messages.length
 end
 ```
 
-Its value is still available to the authorized component renderer, but the
-durable row and Action Cable frame carry only invalidation metadata. It cannot
-be rendered as a scalar `<span>`. Put per-viewer state in `broadcast_payload`,
-which computes a fresh projection for each connection.
+Only `broadcast: :value` observables can render as scalar `<span>` targets.
+Their changed values are stored in `solid_objects_broadcasts` and can reach
+every subscriber that passes `authorize_subscription` for the actor. Put
+per-viewer state in `broadcast_payload`, which computes a fresh projection for
+each connection.
 
 Component names can repeat when each instance has a stable key. Signed
 JSON-compatible locals let one conventional partial render the matching
@@ -530,7 +533,7 @@ class ShoppingCart < SolidObjects::Actor
     end
   end
 
-  observable :items_count do
+  observable :items_count, broadcast: :value do
     items.sum { |item| item.fetch("quantity") }
   end
 end
@@ -1011,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 |
@@ -1035,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
@@ -1082,6 +1094,50 @@ an initializer.
 See the [operations guide](docs/operations.md) for monitoring, reconciliation,
 shutdown, retention, and backup guidance.
 
+## Dashboard
+
+`SolidObjects::Web` is a Rack application that shows instances and their state,
+the mailbox, reminders, effects, broadcasts, dead letters, and the registered
+processes. Mount it inside the application routes, so the Rails session
+middleware runs first:
+
+```ruby
+# config/routes.rb
+require "solid_objects/web"
+
+Rails.application.routes.draw do
+  mount SolidObjects::Web => "/solid_objects/dashboard"
+end
+```
+
+It is not loaded by `require "solid_objects"`: a worker process must not carry
+a web stack. The dashboard and the engine are separate mounts, so an
+application that uses reactive ERB mounts both on different paths.
+
+Every page asks `authorize_administration` before its handler runs, and that
+policy denies by default, so a mount alone exposes nothing. The block receives
+the route's own `action:` and `resource:`, and an `authorization_context:` that
+answers `request`, `session`, and `env`.
+
+The dashboard changes only two things. Retrying a dead letter goes through
+`SolidObjects.dead_letters.retry`, which is idempotent. Pausing an instance
+sets `paused_at` so the activation manager stops claiming that identity; a pass
+already in flight finishes its turn, and a synchronous caller waiting on a
+paused instance times out rather than receiving a result.
+
+The dashboard draws instances per actor type, mailbox depth, and outbox status
+with Chart.js, loaded from a CDN with a subresource integrity hash. A
+deployment with no outbound network access can vendor the file, or turn the
+charts off:
+
+```ruby
+SolidObjects::Web.chart_library_url = "/javascripts/chart.umd.min.js"
+SolidObjects::Web.chart_library_integrity = nil
+```
+
+Read the [dashboard guide](docs/dashboard.md) for the full policy table,
+extension registration, and query cost.
+
 ## Database support
 
 Solid Objects supports:
@@ -1252,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/0009-realtime-updates.md

@@ -9,7 +9,11 @@ Action Cable broadcasts are online-only. A transaction can roll back, a broadcas
 
 ## Decision
 
-The executor evaluates declared observables before and after a successful message. Changed values create broadcast outbox records inside the message commit. A broadcast worker delivers Turbo Stream replacements after commit.
+The executor evaluates declared observables before and after a successful
+message. Changes create invalidation-only broadcast outbox records inside the
+message commit by default. An explicit `broadcast: :value` declaration stores
+the projection and lets a broadcast worker deliver scalar Turbo Stream
+replacements after commit.
 
 One `solid_object` block creates one signed Action Cable subscription and
 contains stable targets for multiple observables and components. Component

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

@@ -169,8 +169,9 @@ turn. `SolidObjects.mutable_copy` creates an independent mutable JSON value.
 `message` and `query` both execute as durable mailbox turns. A query may not
 mutate state. The executor detects query mutation and fails the message. An
 observable is a named projection of state used by server rendering and realtime
-updates. Its durable broadcast row stores the projected value by default;
-`broadcast: :invalidation` stores only an empty invalidation marker.
+updates. Its durable broadcast row stores only an empty invalidation marker by
+default. `broadcast: :value` explicitly opts into storing and sharing the
+projected value.
 
 Lifecycle hooks are deterministic local hooks:
 
@@ -364,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/authorization.md

@@ -13,7 +13,7 @@ intentionally inert until the host application defines its trust boundary.
 | `authorize_query` | Attribute reads, declared queries, committed snapshots, scalar observable reads, initial component rendering, and every component refresh dependency | Explicit call context, the context passed to `solid_object`, or the request context resolved for a component refresh | Actor state or personalized projections can leak across users or tenants |
 | `authorize_destroy` | `reference.destroy` | Value passed as `authorization_context:` | Complete actor state, mailbox, reminders, and pending outboxes can be deleted |
 | `authorize_subscription` | Action Cable subscription to one actor stream | The `ActionCable::Connection` object | Clients can receive future observable updates for other actors |
-| `authorize_administration` | Engine administration controllers, process inspection/cleanup/pruning, message pruning, and dead-letter inspection/retry | Rails controller or `{ source: "cli" }` | Operational metadata, arguments, errors, deletion, and retries become exposed or mutable |
+| `authorize_administration` | Engine administration controllers, every `SolidObjects::Web` page, process inspection/cleanup/pruning, message pruning, and dead-letter inspection/retry | Rails controller, a `SolidObjects::Web` request that answers `request`/`session`/`env`, or `{ source: "cli" }` | Operational metadata, arguments, errors, deletion, and retries become exposed or mutable |
 
 Waiting again through `MessageReference#wait` reauthorizes the stored
 invocation as a message or query. Internal reminder, effect-callback, and
@@ -53,9 +53,9 @@ Component partials receive the resolved value as the
 `authorization_context` local, allowing two authorized viewers to render
 different projections. Responses use `Cache-Control: private, no-store`.
 Durable outbox rows and shared Cable messages never contain component HTML.
-The stream token also signs the scalar observable targets rendered into that
-specific scope. Component-only dependencies send invalidation metadata but not
-their state value to the browser.
+The stream token also signs explicitly value-broadcast scalar observable
+targets rendered into that specific scope. Default component dependencies send
+invalidation metadata but not their state value to the browser.
 
 Keyed components sign their `component_key` and declared JSON-compatible
 locals into the component token. Initial rendering and every refresh pass those
@@ -154,6 +154,13 @@ configuration.authorize_administration = lambda do |authorization_context:, **|
 end
 ```
 
+That policy also denies every `SolidObjects::Web` page, which is the correct
+result for a host whose only administration boundary is shell access. A policy
+that opens the dashboard should separate reading from writing, because
+`action` distinguishes them: `index` and `show` read, while `pause`, `resume`,
+and `retry` change the runtime. The [dashboard guide](dashboard.md) lists the
+action and resource of every page.
+
 Run `bin/rails solid_objects:doctor` after configuration. Its neutral policy
 probe is deliberately conservative: a context-aware policy may correctly warn
 because it denies a `nil` context.

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/correctness.md

@@ -131,9 +131,9 @@ rendering invokes query authorization, Cable separately invokes subscription
 authorization, and the cookie-bearing refresh request invokes query
 authorization again for the component name and every dependency.
 
-The actor stream token separately signs the scalar observable targets rendered
-into its scope. A component dependency that has no scalar target carries only
-its name and revision over Cable, not its serialized value.
+The actor stream token separately signs the explicitly value-broadcast scalar
+observable targets rendered into its scope. A default component dependency
+carries only its name and revision over Cable, not its serialized value.
 
 Cable compares `(instance_id, state_revision)` pairs, coalesces dependencies
 changed by the same turn, and ignores an older pair after a newer one. A new