solid_objects 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17e88ea06322a5e262d146e3d96a0b0d54d2339d46c6681a2fdb0f8d244a3640
-  data.tar.gz: d33b76b4e741921b4e199f3f91af652c06217960606dc7e3e95a03b28d34d3db
+  metadata.gz: 935a2d2bb12fbc5b39121fe44004d0cc0671c3bef82012cf9b024089c3546ac9
+  data.tar.gz: 15de97ea8547bfb552ae848b2ae523fdd6c48a557313ba3fd87d931ee770f9b1
 SHA512:
-  metadata.gz: 0a217bfdb8454acbf7caa7a153095455e8b421aab4ebc7a16be056efa49db78bc4e0c452f50e24c04f1aad5177aafdb16ebff67a974618a0134c302581edf85a
-  data.tar.gz: 284a15eb44417ebaad3ec0ccad3b180999ed94df9d7ca73b74fcc70ed136f3458613ecbadb99115f13e93310d684a0451a62f6887dd7b0c2bdcf1af14ade2fcf
+  metadata.gz: 6633846db212684a9e6d687f76e559cd51448171bd9e067534024e9a067534f1ff7eab223e3c1ab80b7a02765b909a324f2dbb9b1f527e5846d933de5b3639c7
+  data.tar.gz: ce930198b48379439c4947dd41ea5d3a0577ad8ce49eb1513715075ccf23c03b23237bcee77f06a898ea5460b83e3bf6b0c8a54f7b9c16e03c159c2572a03306

data/CHANGELOG.md

@@ -1,5 +1,86 @@
 # Changelog
 
+## 0.10.0 - 2026-08-10
+
+- Report a denied CLI command as a policy decision rather than a crash.
+  Administration denies by default, so an unconfigured host met a thirty-line
+  Ruby backtrace on its first `solid_objects` command. The executable now
+  prints the refusal and the setting that grants access, and exits 1.
+- Measure the query count for a synchronous call. `benchmark/query_count.rb`
+  only measured a worker turn, so the documented synchronous number had no
+  script behind it. It reports three now: a message turn costs 26 queries
+  rather than the documented 29, the caller of a synchronous call costs 49, and
+  a synchronous call in total costs 75, being a caller plus the turn it waits
+  on. Counting is scoped to the measuring thread, since a worker loop polls
+  whether or not a call is in flight and a process-wide count folds those polls
+  into the result.
+
+- Run payload broadcast blocks against the actor instance, like every other
+  block in the actor DSL. `self` was the actor class, so an actor instance
+  method called from a payload block raised
+  `NoMethodError: undefined method 'x' for class PlaymatRoom`. Blocks keep
+  receiving the actor and the authorization context as arguments, so the
+  documented signature is unaffected. A block that relied on the class receiver
+  now raises `InvalidPayloadBroadcast` naming the method and the change instead
+  of an unexplained `NameError`.
+- Add `payload_authorization_context`, the payload counterpart to
+  `component_authorization_context`. Payloads are computed inside the channel,
+  so without a resolver the payload block and its `authorize_query` call
+  received the raw Action Cable connection while a controller render passed an
+  application object, and the authorization hook had to tell them apart. The
+  resolver may also accept `payload_name:`. It defaults to returning the
+  connection unchanged.
+- Confine a failing payload to itself. A raising payload block propagated out of
+  the channel: on subscribe it rejected the subscription, and on a broadcast it
+  abandoned the remaining payload names, which showed up in the browser only as
+  reactive updates that stopped arriving. A failure is now reported as
+  `solid_objects.payload_broadcast_failed` with the actor type, actor id,
+  payload name, and exception class, and delivery continues. The exception
+  message is deliberately excluded so subscriber state cannot leak into logs. A
+  revision with a failed payload does not advance the delivery watermark, so a
+  transient failure is retried on the next broadcast instead of being recorded
+  as delivered and deduplicated away.
+- Run retention on the supervisor rather than leaving it configured but
+  unscheduled. Every actor call writes a durable message row, so a policy that
+  nothing invokes let history grow without bound until an application scheduled
+  its own job. `retention_interval` defaults to one hour, and zero disables it.
+  Retention runs on its own thread, so a slow pass cannot delay replacing a
+  crashed role, and a failed pass retries at monitor cadence with a doubling
+  backoff rather than deferring for the whole interval.
+- Batch component refreshes on reconnect. A reconnecting subscription refreshed
+  every stale component individually, ignoring the batches those components
+  declared, so a page with twenty batched components issued twenty requests
+  instead of one. That happens at the worst moment: a server restart reconnects
+  every client at once. Reconnect now shares the batching the live invalidation
+  path uses.
+- Cover the reconnect burst in the browser suite: convergence of batched and
+  unbatched components, an inert replay of an already-applied revision,
+  cancellation of the request left in flight by the drop, incarnation ordering
+  after a destroy and recreate, and payload delivery exactly once per revision.
+- Add Ruby 4.0 to the compatibility matrix, which now covers Ruby 3.3, 3.4, and
+  4.0 against Rails 8.0 and 8.1.
+
+## 0.9.0 - 2026-08-10
+
+- Add a browser test suite running the refresh modules against real Chromium and
+  a real Turbo build, covering `component_refresh.js`, which previously had no
+  tests at all. Every batching defect that reached production passed the jsdom
+  suite, because jsdom cannot model Turbo applying a morph, task boundaries
+  between socket deliveries, or abort semantics.
+- Verify the database server. Each adapter reports its version against the
+  oldest one Solid Objects is exercised against, PostgreSQL 13, MySQL 8.0, and
+  SQLite 3.35, and MySQL additionally confirms that Solid Objects tables use
+  InnoDB, since a non-transactional engine would silently break fenced commits.
+  The doctor reports this as `database_server` and warns rather than failing:
+  refusing to run on an untested server would be a worse failure than running
+  on one.
+- Add `SolidObjects::WakeUpAdapters::Redis`, an optional cross-process wake-up
+  using Redis publish and subscribe. This is the option for MySQL, which has no
+  notification primitive. Measured cross-process wake-up latency drops from
+  103.8 ms to 5.7 ms at p50. One background subscription per process fans out to
+  every waiting role in memory. The `redis` gem is not a dependency of this gem,
+  and `WakeUpAdapters.for` does not select it, so adopting Redis stays explicit.
+
 ## 0.8.0 - 2026-08-10
 
 - Replace a supervised role whose thread died. A role that raised left its

data/app/controllers/solid_objects/components_controller.rb

@@ -138,26 +138,11 @@ module SolidObjects
     # @rbs (Array[ComponentRegistration]) -> untyped
     def component_authorization_context(registrations)
       callable = SolidObjects.configuration.component_authorization_context
-      return callable.call(controller: self) unless accepts_registrations?(callable)
-
-      callable.call(controller: self, registrations:)
-    end
-
-    # A lambda answers `parameters` directly; a callable object answers it
-    # through its `call` method.
-    # @rbs (untyped) -> bool
-    def accepts_registrations?(callable)
-      callable_parameters(callable).any? do |type, name|
-        type == :keyrest || (%i[key keyreq].include?(type) && name == :registrations)
+      unless CallableKeywords.accepts?(callable, :registrations)
+        return callable.call(controller: self)
       end
-    end
-
-    # @rbs (untyped) -> Array[[ Symbol, Symbol ]]
-    def callable_parameters(callable)
-      return callable.parameters if callable.respond_to?(:parameters)
-      return callable.method(:call).parameters if callable.respond_to?(:call)
 
-      []
+      callable.call(controller: self, registrations:)
     end
 
     # @rbs (ComponentRegistration) -> Hash[Symbol, untyped]

data/benchmark/support.rb

@@ -291,24 +291,66 @@ module SolidObjectsBenchmark
 
     # @rbs () -> void
     def query_count
+      turn = message_turn_query_count
+      caller_queries = synchronous_caller_query_count
+      puts "database queries: #{turn} for 1 message turn"
+      puts "database queries: #{caller_queries} for the caller of 1 synchronous call"
+      puts "database queries: #{caller_queries + turn} for 1 synchronous call, caller plus the turn it waits on"
+    end
+
+    private
+
+    # Runs the turn on the measuring thread, so nothing else can contribute.
+    # @rbs () -> Integer
+    def message_turn_query_count
       CounterActor.ref("queries").async(:increment)
       worker = SolidObjects::Worker.new
+      count_queries { worker.run_once }
+    ensure
+      worker&.stop
+    end
+
+    # A synchronous call also registers or heartbeats the caller process,
+    # claims the activation, and observes the result, so the caller costs more
+    # than the turn it waits on. Only the caller thread is counted; the worker
+    # runs on its own thread and its turn is measured separately, because a
+    # worker loop also polls and those polls belong to no particular call. The
+    # first call is discarded because it pays for activation and caller
+    # registration that a steady-state call does not.
+    # @rbs () -> Integer
+    def synchronous_caller_query_count
+      reference = CounterActor.ref("sync-queries")
+      worker = SolidObjects::Worker.new
+      runner = Thread.new { worker.run }
+      reference.sync(:increment)
+      count_queries { reference.sync(:increment) }
+    ensure
+      worker&.request_shutdown
+      runner&.join(5)
+      worker&.stop
+    end
+
+    # Subscriptions are process-wide and notifications run on the thread that
+    # issued the query, so counting is scoped to the measuring thread. Without
+    # that, a worker polling in the background inflates the count by however
+    # many times it happened to poll during the window.
+    # @rbs () { () -> untyped } -> Integer
+    def count_queries
+      measuring = Thread.current
       queries = 0
       subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |event|
+        next unless Thread.current.equal?(measuring)
         next if %w[SCHEMA TRANSACTION].include?(event.payload[:name])
         next if event.payload[:cached]
 
         queries += 1
       end
-      processed = worker.run_once
-      puts "database queries: #{queries} for #{processed} message"
+      yield
+      queries
     ensure
       ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
-      worker&.stop
     end
 
-    private
-
     # @rbs (ComponentRegistration, untyped, ?snapshot: ActorSnapshot?) -> untyped
     def render_component(registration, view_context, snapshot: nil)
       SolidObjects::ComponentRenderer.new(

data/docs/benchmarks.md

@@ -40,8 +40,25 @@ scenario used four worker threads.
 | Process, four workers | 556.5 messages/s |
 | Synchronous latency | p50 1.8 ms, p95 25.6 ms, p99 156.2 ms |
 | Activation reuse | 98.0%, four activations for 200 messages |
-| Queries for one message turn | 29 |
-| Queries for one synchronous call | 49 |
+
+Query counts are a property of the code rather than the host, so they are
+tracked separately. Re-measured 2026-08-10 against 0.10.0 on SQLite with
+`bundle exec ruby benchmark/query_count.rb`, which is deterministic across runs:
+
+| Scenario | Queries |
+| --- | ---: |
+| One message turn | 26 |
+| The caller of one synchronous call | 49 |
+| One synchronous call, caller plus the turn it waits on | 75 |
+
+A worker turn fell from the 29 recorded earlier. The caller count is unchanged
+at 49, and the combined figure is new: a synchronous call is a caller and a
+worker turn, and only the sum says what the database actually serves.
+
+Counting is scoped to the measuring thread. A worker loop polls whether or not
+a call is in flight, so a process-wide count folds however many polls happened
+to land inside the window into the result. That is also why the caller and the
+turn are measured separately rather than by watching both threads at once.
 
 A synchronous call costs far more queries than a worker turn because the caller
 also registers or heartbeats its caller process, claims the activation, and

data/docs/local-testing.md

@@ -0,0 +1,91 @@
+# Local testing
+
+The default suite runs against SQLite and needs nothing extra:
+
+```bash
+bundle exec rake
+```
+
+Everything below is optional. Each adapter and each optional service skips its
+tests when the service is absent, so a missing container degrades coverage
+rather than breaking the run. That is convenient, and it is also a trap: a
+skipped test looks identical to a passing one in the summary line. Check the
+skip count when a change touches an adapter.
+
+## PostgreSQL
+
+```bash
+brew services start postgresql@17
+createuser -h 127.0.0.1 -s solid_objects
+psql -h 127.0.0.1 -d postgres -c "ALTER USER solid_objects WITH PASSWORD 'solid_objects';"
+createdb -h 127.0.0.1 -O solid_objects solid_objects_test
+
+SOLID_OBJECTS_DATABASE_URL=postgresql://solid_objects:solid_objects@127.0.0.1:5432/solid_objects_test \
+  bundle exec rake test
+```
+
+Running this locally is worth the setup: it is what caught the PostgreSQL
+version comparison reading a packed integer, where `170010` compared greater
+than any minimum and made the check useless on the adapter it mattered most for.
+
+## MySQL and Redis in Docker
+
+These use non-default ports so they cannot collide with a MySQL or Redis that
+another project is already running:
+
+```bash
+docker run -d --name so-mysql -p 3307:3306 \
+  -e MYSQL_ROOT_PASSWORD=solid_objects \
+  -e MYSQL_DATABASE=solid_objects_test \
+  -e MYSQL_USER=solid_objects \
+  -e MYSQL_PASSWORD=solid_objects \
+  mysql:8
+
+docker run -d --name so-redis -p 6380:6379 redis:7-alpine
+```
+
+```bash
+SOLID_OBJECTS_DATABASE_URL=mysql2://solid_objects:solid_objects@127.0.0.1:3307/solid_objects_test \
+  bundle exec rake test
+
+SOLID_OBJECTS_REDIS_URL=redis://127.0.0.1:6380/15 \
+  bundle exec rake test TEST=test/integration/redis_wake_up_test.rb
+```
+
+Stop them with `docker rm -f so-mysql so-redis`.
+
+## Recreating a database between runs
+
+The test helper migrates unconditionally, so a second run against a database
+that already has the tables fails with a duplicate-table error rather than a
+test failure. Recreate first:
+
+```bash
+dropdb -h 127.0.0.1 solid_objects_test && createdb -h 127.0.0.1 -O solid_objects solid_objects_test
+
+docker exec so-mysql mysql -u root -psolid_objects \
+  -e "DROP DATABASE IF EXISTS solid_objects_test; CREATE DATABASE solid_objects_test;
+      GRANT ALL ON solid_objects_test.* TO 'solid_objects'@'%';"
+```
+
+## Rails and Ruby span
+
+`RAILS_VERSION` pins the Rails line the gemspec advertises:
+
+```bash
+RAILS_VERSION=8.0 bundle install
+RAILS_VERSION=8.0 bundle exec rake test
+```
+
+## Browser modules
+
+```bash
+npm install
+npm test                                  # jsdom, fast
+npx playwright install chromium
+npm run test:browser                      # real Chromium and a real Turbo build
+```
+
+The jsdom suite covers logic; the browser suite covers integration with Turbo.
+Both matter: every batching defect that reached production passed the jsdom
+suite alone.

data/docs/realtime.md

@@ -128,8 +128,21 @@ configuration.wake_up_adapter = SolidObjects::WakeUpAdapters.for
 default on SQLite and MySQL, so the same line is safe across adapters. Name
 `SolidObjects::WakeUpAdapters::Postgresql.new` directly to require it.
 
-MySQL has no notification primitive, so MySQL applications keep polling and tune
-`polling_interval`.
+MySQL has no notification primitive. MySQL applications either keep polling and
+tune `polling_interval`, or configure the Redis adapter:
+
+```ruby
+configuration.wake_up_adapter = SolidObjects::WakeUpAdapters::Redis.new(
+  url: ENV["REDIS_URL"]
+)
+```
+
+Measured latency for a cross-process wake-up drops from 103.8 ms to 5.7 ms at
+p50. The `redis` gem is not a dependency of this gem, so applications add it
+themselves. One background subscription per process fans out to every waiting
+role in memory, rather than one connection per thread, and `WakeUpAdapters.for`
+does not select it: Redis is infrastructure this gem otherwise does not require,
+so choosing it is explicit.
 
 Measured latency for a cross-process wake-up drops from 103.7 ms to 2.9 ms at
 p50. The adapter keeps `polling_interval` as the upper bound: a missed or failed
@@ -224,9 +237,11 @@ single actor mutation changes several components, an application pays several
 round trips for one logical update. A payload broadcast collapses that into one
 message on the stream the page already has open.
 
-Declare the payload on the actor. The block receives the actor and the
-subscriber's authorization context, and it runs **once per subscriber**, so two
-sessions watching the same actor never see each other's private state:
+Declare the payload on the actor. The block runs against the actor instance,
+like every other block in the actor DSL, and receives the actor and the
+subscriber's authorization context as arguments. It runs **once per
+subscriber**, so two sessions watching the same actor never see each other's
+private state:
 
 ```ruby
 class PlaymatRoom < SolidObjects::Actor
@@ -246,6 +261,16 @@ class PlaymatRoom < SolidObjects::Actor
 end
 ```
 
+Because the block runs against the actor, an actor instance method is reachable
+without a receiver, so shared logic does not have to be duplicated into the
+block:
+
+```ruby
+broadcast_payload :playmat_state do |_room, authorization|
+  { "turn" => turn, "hand" => hand_for(authorization.session_id) }
+end
+```
+
 Subscribe the scope to it:
 
 ```erb
@@ -285,6 +310,26 @@ Payload blocks read committed actor state through the same snapshot components
 use. They cannot write application records, and the return value must be a JSON
 object or array so the wire format stays inspectable.
 
+A payload is one subscriber's view of one name, so a failure is confined to it.
+A raising block does not reject the subscription, stop the other payload names,
+or stop component refreshes on the same connection. The failure is reported as
+`solid_objects.payload_broadcast_failed` carrying the actor type, actor id,
+payload name, and exception class. The exception message is deliberately not
+included: a payload block reads subscriber state, so its message is the one
+place that state could leak into logs.
+
+A revision with a failed payload does not advance the delivery watermark, so a
+transient failure is retried on the next broadcast rather than being recorded as
+delivered. Retries are driven by broadcasts rather than a timer, so a payload
+that fails persistently retries once per actor mutation and reports each
+attempt. A repeating stream of `payload_broadcast_failed` for one `payload_name`
+therefore means a persistent fault in that block, not a one-off; a single event
+that does not recur was transient and has already been recovered.
+
+A payload the subscriber cannot query is skipped rather than served partially;
+that decision is stable, so it settles the revision and the skip is silent by
+design.
+
 ### mtg-playmat before and after
 
 Before, one mutation that touched three observables produced three refresh
@@ -337,13 +382,31 @@ end
 Callbacks that accept only `controller:` continue to work; the extra keyword is
 passed only to callables that declare it.
 
-The three contexts are intentionally different:
+Payloads have the same resolver, because they are computed inside the channel
+rather than in a controller. Without one, a payload block and its
+`authorize_query` call receive the Cable connection while a controller render
+passes an application object, and the authorization hook has to tell them
+apart. Resolve both to the same type and it does not:
+
+```ruby
+configuration.component_authorization_context = ->(controller:) { controller.current_account }
+configuration.payload_authorization_context = ->(connection:) { connection.current_account }
+```
+
+The resolved value is what the payload block receives as its second argument and
+what `authorize_query` receives as `authorization_context`. A resolver may also
+accept `payload_name:` when the subject depends on which payload was requested.
+The default returns the connection unchanged, so an application that has not
+configured one is unaffected.
+
+The contexts are intentionally different:
 
 | Boundary | Authorization context |
 | --- | --- |
 | Initial Action View render | Explicit `authorization_context:` passed to `solid_object` |
 | Action Cable subscription | The authenticated Cable connection |
 | Component refresh | Value returned by `component_authorization_context` for the engine controller request |
+| State payload | Value returned by `payload_authorization_context` for the Cable connection |
 
 Do not substitute a signed token for any of them. Keys and locals are visible
 to the browser and signed for integrity, not encrypted or authorized. Never
@@ -380,6 +443,11 @@ ordered commits within one incarnation. Out-of-order invalidations at or below
 the last transmitted pair are ignored. The durable state row remains source of
 truth.
 
+Stale components that share a `batch:` are refreshed together, exactly as a
+live invalidation refreshes them, so reconnecting costs one request per batch
+rather than one per component. That matters most on a restart, when every
+client reconnects at once.
+
 The component endpoint rejects a requested revision newer than the committed
 snapshot. This is a final server-side guard; browser safety primarily comes
 from monotonic channel filtering plus replace-frame detachment or morph

data/docs/roadmap.md

@@ -13,17 +13,27 @@
 - At-least-once retries, terminal domain rejection, strict poison ordering,
   dead letters, and tail retry
 - Transactional effects with success/failure actor messages
-- Actor-to-actor asynchronous outbox delivery
+- Actor-to-actor asynchronous outbox delivery. Effects and broadcasts use
+  portable status rows with polling indexes and database check constraints on
+  status, which works on all three adapters; a future version may add narrow
+  ready/claimed membership tables for very large outboxes, as messages already
+  have
 - One-shot and recurring reminders with `:latest` or `:all` catch-up
 - Durable observable invalidations, scalar Turbo replacement, keyed ERB
   components, signed component locals, and authorized replace or morph refresh
 - Batched component refreshes: components sharing a signed `batch:` collapse to
   one browser request per revision, served as HTML frames in a JSON envelope
 - Personalized state payload broadcasts computed per subscriber under that
-  subscriber's authorization context, fenced by actor revision
+  subscriber's authorization context, fenced by actor revision, resolved through
+  `payload_authorization_context` so the block and `authorize_query` see the
+  same subject a controller render passes, and confined so one failing payload
+  cannot reject the subscription or stop its siblings
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
   migration cookbook
+- Database server verification: each adapter reports its version against a
+  tested minimum, MySQL confirms Solid Objects tables use InnoDB, and the
+  doctor warns rather than refusing to run on an untested server
 - Handler Active Record write isolation, same-database commit actions, ambient
   transaction rejection, adapter lock/query deadlines, bounded SQLite lock
   retries outside those deadlines, structured sync timeout diagnostics, and
@@ -32,62 +42,72 @@
   graceful caller shutdown, committed state snapshots, and an opt-in Minitest
   helper
 - Supervisor role replacement: a role whose thread dies is restarted until
-  shutdown is requested, and dead process records are pruned on an interval
+  shutdown is requested, and dead process records plus expired message and
+  process history are pruned on their own intervals without an application
+  scheduling its own job
 - SQLite, PostgreSQL, and MySQL integration suites
 - Opt-in cross-process wake-up on PostgreSQL through `WakeUpAdapters.for`, with
   a listening connection per waiting thread and release on supervisor shutdown
+- Opt-in cross-process wake-up on Redis, the option for MySQL applications,
+  measured at 103.8 ms to 5.7 ms at p50; the `redis` gem stays outside this
+  gem's dependencies
 - Inline RBS generation/validation, Steep, Standard Ruby, Solid Queue's exact
   RuboCop policy, and a warning-free Brakeman scan
-- Compatibility CI across the supported span: Ruby 3.3 and 3.4 against Rails 8.0
-  and 8.1, pinned through `RAILS_VERSION` so the advertised range is verified
-  rather than assumed
-- A JavaScript suite covering the state payload and batched refresh browser
-  modules, run in CI with Node's test runner and jsdom, with every GitHub
-  Actions reference pinned to a commit SHA
+- Compatibility CI across the supported span: Ruby 3.3, 3.4, and 4.0 against
+  Rails 8.0 and 8.1, pinned through `RAILS_VERSION` so the advertised range is
+  verified rather than assumed
+- A JavaScript suite covering every browser module, run in CI with Node's test
+  runner and jsdom, plus a browser suite running the same modules against real
+  Chromium and a real Turbo build, with every GitHub Actions reference pinned to
+  a commit SHA. The browser suite covers the reconnect burst: convergence of
+  batched and unbatched components, an inert replay of an applied revision,
+  cancellation of the request left in flight by the drop, incarnation ordering
+  after a destroy and recreate, and payload delivery exactly once per revision
 
 ## Partially implemented
 
-- Wake-up strategy: in-process signaling, durable polling, injection, and an
-  opt-in PostgreSQL notification adapter are implemented; a Redis adapter is
-  not. In-process signaling cannot cross process boundaries, so without the
-  adapter a commit in a web process does not wake a broadcast executor in a
-  worker process and that delivery waits up to `polling_interval`, 100 ms by
-  default. `WakeUpAdapters.for` removes that delay on PostgreSQL, measured at
-  103.7 ms to 2.9 ms at p50. It is opt-in rather than automatic: it opens a
-  connection per waiting thread outside the pool, and `LISTEN` does not survive
-  a transaction-pooling proxy such as PgBouncer. MySQL has no notification
-  primitive, so MySQL applications keep polling.
+- Wake-up strategy: in-process signaling, durable polling, injection, and
+  cross-process adapters for PostgreSQL and Redis are implemented and tested.
+  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.
+  `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
+  configure Redis explicitly.
 - Realtime: scalar and dependency-driven keyed ERB component replacement or
   morphing, personalized refresh authorization, revision fencing, coalescing,
   reconnect convergence, batched refreshes, and personalized state payloads are
   implemented; application-directed Turbo append intents are not. Batch
   coalescing happens in the browser rather than the broadcast executor, so one
   commit still sends one Action Cable message per changed observable even
-  though it costs one browser request.
+  though it costs one browser request. Reconnect convergence previously
+  bypassed batching entirely, issuing one request per stale component at the
+  moment a restart reconnects every client at once; it now shares the batching
+  the live invalidation path uses. Payload delivery over Action Cable was
+  untested end to end, which is how a raising payload block came to reject the
+  subscription; it is now covered and confined, and the payload authorization
+  context is resolved through `payload_authorization_context` rather than
+  handing the block a raw Cable connection.
 - Backpressure: mailbox/payload/state/result caps and fair yields exist;
   distributed per-actor rate limits and global admission control do not.
 - Administration: actor and dead-letter views plus policy hooks exist; richer
   filtering, audit records, and bulk-safe tools do not.
-- Browser module coverage: the state payload and batched refresh modules have
-  JavaScript tests; `component_refresh.js`, which drives individual morph
-  refreshes, does not.
-- Outboxes use portable status rows with polling indexes; future versions may
-  introduce narrow ready/claimed membership tables for very large outboxes.
 
 ## Next milestones
 
-1. Add an optional Redis wake-up adapter, which is the remaining cross-process
-   option for MySQL. The PostgreSQL notification adapter, its latency
-   benchmark, and its concurrency tests are implemented.
-2. Add result lookup by request ID and broader deadlock retry classification.
-3. Add scheduled retention and stale-process maintenance.
-4. Add database/server-version checks and MySQL InnoDB verification at boot.
-5. Add Turbo append intents and expand reconnect coverage in a full browser.
-6. Add distributed rate limits, global admission hooks, and cache-capacity
+1. Add result lookup by request ID and broader deadlock retry classification.
+2. Add Turbo append intents.
+3. Add distributed rate limits, global admission hooks, and cache-capacity
    eviction.
-7. Expand security scanning and run compatibility CI across supported Rails and
-   Ruby versions.
-8. Benchmark all workloads under documented hardware/database settings and
+4. Expand security scanning beyond the Brakeman scan, such as dependency
+   auditing and secret scanning.
+5. Benchmark all workloads under documented hardware/database settings and
    publish adapter-specific adoption measurements. Throughput, synchronous
    latency, query counts, and the three reactive delivery paths are measured on
    SQLite; adapter-specific and end-to-end browser measurements are not.

data/exe/solid_objects

@@ -6,4 +6,15 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "solid_objects"
 require "solid_objects/cli"
 
-SolidObjects::CLI.start(ARGV)
+begin
+  SolidObjects::CLI.start(ARGV)
+rescue SolidObjects::Unauthorized => error
+  # Authorization denies by default, so this is what an unconfigured host sees
+  # from its first command. A policy decision is not a crash, and printing a
+  # backtrace for one buries the single line that says how to grant access.
+  warn "solid_objects: #{error.message}"
+  warn "Set configuration.authorize_administration in your Solid Objects " \
+    "initializer to allow this command. See the commented example in " \
+    "config/initializers/solid_objects.rb."
+  exit 1
+end

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

@@ -52,6 +52,14 @@ SolidObjects.configure do |configuration|
   # Configure component_authorization_context to return the authenticated
   # principal used for reactive component refreshes.
 
+  # Payloads are delivered over Action Cable, so without a resolver the payload
+  # block and authorize_query receive the Cable connection while a controller
+  # render passes an application object. Resolve both to the same type and the
+  # authorization hook stops having to tell them apart:
+  #
+  # configuration.component_authorization_context = ->(controller:) { controller.current_account }
+  # configuration.payload_authorization_context = ->(connection:) { connection.current_account }
+
   # On hosts where shell access is already an authenticated administrative
   # boundary, this enables only gem commands that pass the CLI context:
   #