docs: correct what the docs claim about wake-up

Three documents still described the old opt-in behaviour. The realtime
guide told readers to assign `WakeUpAdapters.for` and said Redis is never
selected, the operations guide said the warning fires when no adapter is
configured, and ADR 0011 recorded no decision about choosing one.

Each now describes the setting, automatic selection, the probe, the
downgrade that says why, and where to read the installed capability.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: cardmagic

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

@@ -25,6 +25,14 @@ The interface supports:
 
 MySQL uses polling or optional Redis. SQLite uses polling plus the in-process signal; multi-host SQLite is outside its supported operating model.
 
+Selection is automatic. `wake_up_adapter` takes a name or an adapter and
+defaults to `:automatic`, which prefers a configured Redis URL, then PostgreSQL
+notifications, then polling. PostgreSQL is chosen only after a probe
+notification arrives, because `LISTEN` does not survive a transaction pooler. A
+requested adapter that the environment cannot provide polls and records why,
+rather than claim a wake-up it cannot deliver. `SolidObjects.wake_up.capability`
+reports the choice, and the doctor reports the same record.
+
 The synchronous caller first attempts to claim and execute the actor locally,
 so the normal path has no worker polling leg. When another process owns the
 activation, coordination overhead from completion commit until the caller's
@@ -45,5 +53,7 @@ Timeout does not cancel durable work.
 - 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.
+- A multi-process deployment whose installed adapter cannot cross processes trades idle database load for up to the current idle polling interval of notification latency and logs that topology once.
+- A PostgreSQL deployment that configures nothing now pays one `NOTIFY` per enqueue after the commit and one listening connection per waiting thread, outside the pool.
+- Selection runs once per process, under a lock, because the probe opens connections and waits.
 - Notification payloads never contain actor arguments or results.

docs/operations.md

@@ -245,13 +245,27 @@ 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.
+Solid Objects selects a wake-up adapter on first use. `wake_up_adapter` defaults
+to `:automatic`, which prefers `SOLID_OBJECTS_REDIS_URL`, then PostgreSQL
+notifications, then polling. `SolidObjects.wake_up.capability` and the
+`wake_up` doctor check report what was installed, whether it crosses processes,
+its measured floor, and why.
+
+The in-process signal interrupts waits only in the current Ruby process. When a
+live process record shows that the database is shared across processes and the
+installed adapter does not cross them, the runtime logs
+`solid_objects.polling_only_cross_process_wake_up` once. Newly committed work
+can then wait up to the current idle polling interval.
+
+On PostgreSQL, selection proves the path first: it listens on a probe channel,
+notifies it from a second connection, and waits for the notification. A probe
+that does not arrive logs `solid_objects.wake_up.pooled_session` once and falls
+back to polling, because `LISTEN` does not survive a transaction pooler such as
+PgBouncer. A requested adapter that the environment cannot provide, such as
+`:postgresql` on MySQL or `:redis` without `SOLID_OBJECTS_REDIS_URL`, logs
+`solid_objects.wake_up.unavailable` once and polls rather than claim a
+cross-process wake-up that cannot happen. Only an unknown name is refused, and
+`configure` refuses it at boot.
 
 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

docs/realtime.md

@@ -140,46 +140,52 @@ explicitly serve the module. Turbo's normal morph rules still apply; use
 
 ## Cross-process wake-up
 
-Runtime roles poll for work and are woken early by an in-process signal. That
-signal cannot cross process boundaries, so a commit in a Puma process does not
-wake a broadcast executor in a worker process, and delivery waits out
+Runtime roles poll for work and are woken early by a signal. An in-process
+signal cannot cross process boundaries, so a commit in a Puma process would not
+wake a broadcast executor in a worker process, and delivery would wait out
 `polling_interval`, 100 ms by default.
 
-On PostgreSQL, install the notification adapter to remove that delay:
+Solid Objects selects the adapter for you. `wake_up_adapter` defaults to
+`:automatic`, which prefers a configured Redis URL, then PostgreSQL
+notifications, then polling:
 
 ```ruby
 # config/initializers/solid_objects.rb
-configuration.wake_up_adapter = SolidObjects::WakeUpAdapters.for
+configuration.wake_up_adapter = :automatic     # the default
+configuration.wake_up_adapter = :in_process    # opt out
+configuration.wake_up_adapter = :postgresql    # force one
+configuration.wake_up_adapter = MyAdapter.new  # your own
 ```
 
-`WakeUpAdapters.for` returns notifications on PostgreSQL and the in-process
-default on SQLite and MySQL, so the same line is safe across adapters. Name
-`SolidObjects::WakeUpAdapters::Postgresql.new` directly to require it.
-
-MySQL has no notification primitive. 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.
+`SolidObjects.wake_up.capability` reports what was installed, whether it crosses
+processes, its measured floor, and why. `bin/rails solid_objects:doctor` reports
+the same record.
 
+On PostgreSQL, selection proves the path before it chooses it. It listens on a
+probe channel, sends one `NOTIFY` from a second connection, and waits for it to
+arrive, because `LISTEN` does not survive a transaction pooler such as
+PgBouncer. A probe that does not deliver falls back to polling and warns once.
 Measured latency for a cross-process wake-up drops from 103.7 ms to 2.9 ms at
 p50. The adapter keeps `polling_interval` as the upper bound: a missed or failed
 notification costs latency, never correctness, and signalling never raises into
 the caller that committed. `LISTEN` needs its own connection, so the adapter
 opens one outside the pool and releases it on `stop`.
 
-Applications on SQLite or MySQL, or that do not configure the adapter, keep the
-existing polling behaviour.
+MySQL has no notification primitive, so MySQL applications either keep polling
+and tune `polling_interval`, or set `SOLID_OBJECTS_REDIS_URL`, which selects
+Redis on any database:
+
+```bash
+SOLID_OBJECTS_REDIS_URL=redis://localhost:6379/0
+```
+
+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, and selection polls and says so when the gem is missing. One
+background subscription per process fans out to every waiting role in memory,
+rather than one connection per thread. Name
+`SolidObjects::WakeUpAdapters::Redis.new(url:)` directly for a URL that does not
+come from the environment.
 
 ## Batched component refreshes