solid_objects 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15ee987ca3dcf3419f28902e2a0c18c8444c834964b743f3e7b99cd5f6dcde33
-  data.tar.gz: 45bf4d0449184c9fbf3718ce088f8541b68049e9458ee8802947fd74bef1fadb
+  metadata.gz: 8dc01a4c7b7f44d7dbd68b1194abd64a2c5515d5280a1e9cae15b119ff18508c
+  data.tar.gz: 68099ea645dff1d976f9aeda77d79d04ed8280e18bfc6d4235daca972ffafad4
 SHA512:
-  metadata.gz: 6b5b29a7f3052c1a04a012f348a9f8f1054500056073b34c8b2a6680f7d84db195efbe0d5d68809b33ba7bed04af1c141777a27801e6049df0863311cd948a25
-  data.tar.gz: 93e7bdeb0ee3a1a0c4f212f5da40c25d61bca88b1ea2dc87efb4b09d199068b5374452beb991baec05b573ac3e0109ca86dde37463a7cf5f28d823f02969767a
+  metadata.gz: 335cec6b8f87328e9a88eee32bbd8aaca5b019cb0ef76dfa70f5efa261afb81a2a034d3bc6a11189f22c4809583d9cce1538c6ecb1ff8cc8319c1d195fec8295
+  data.tar.gz: 445c227d5badd737cb44f9b44b87917b73c3e2a55a66acb6a4cd1fe09a39febda314f00188cd35eabc70acef5d5b95503c3cedf5c35632e22948fa62667a62db

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 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
+  detect changes and refresh reactive components, but persist `{}` and send no
+  scalar value over Action Cable. Document that ordinary observable values are
+  shared with every authorized actor subscriber and that subscriber-specific
+  state belongs in a payload projection.
+- **Breaking:** include the originally staged `arguments:` in effect success
+  and failure callbacks so actors can correlate concurrent effects.
+- Accept identifier-style rejection codes, including camelCase and symbols,
+  and fail malformed codes once with non-retryable
+  `SolidObjects::InvalidRejectionCode` diagnostics.
+- Add `run_due_reminders(now:)` to `SolidObjects::TestHelper` for deterministic
+  reminder tests without sleeping or mutating runtime rows.
+
 ## 0.12.0 - 2026-08-13
 
 - Replace positional actor dispatch with fluent operation selection. Direct

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,6 +206,23 @@ dependencies changes:
 <% end %>
 ```
 
+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 :message_count, broadcast: :value do
+  recent_messages.length
+end
+```
+
+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
 projection:
@@ -515,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
@@ -736,8 +754,8 @@ JSON-compatible details. The rejected message remains durable for audit, actor
 state is rolled back, and no later mailbox turn is blocked.
 
 `Rejected#code` is a `String`, even when `reject` receives a symbol. Codes must
-match `\A[a-z][a-z0-9_]*\z`; invalid codes raise `ArgumentError` when the
-handler calls `reject`.
+match `\A[A-Za-z_][A-Za-z0-9_]*\z`. Invalid codes raise
+`SolidObjects::InvalidRejectionCode` and fail the turn without retrying.
 
 ### Redelivery
 
@@ -819,11 +837,11 @@ def checkout(payment_id:, amount_cents:)
   )
 end
 
-def payment_succeeded(effect_id:, result:)
+def payment_succeeded(effect_id:, arguments:, result:)
   self.checkout_status = "paid"
 end
 
-def payment_failed(effect_id:, error:)
+def payment_failed(effect_id:, arguments:, error:)
   self.checkout_status = "failed"
 end
 ```
@@ -842,6 +860,10 @@ end
 
 The provider call can repeat if a process dies after external success but
 before recording completion. The stable effect ID is the idempotency key.
+Success callbacks receive `effect_id:`, the originally staged `arguments:`,
+and `result:`. Failure callbacks receive `effect_id:`, `arguments:`, and
+`error:`, so an actor can correlate concurrent effects without storing a
+separate callback ledger.
 
 ## Reminders
 
@@ -1063,6 +1085,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:

data/app/models/solid_objects/broadcast.rb

@@ -6,5 +6,13 @@ module SolidObjects
 
     belongs_to :message, class_name: "SolidObjects::Message"
     belongs_to :instance, class_name: "SolidObjects::Instance"
+
+    # @rbs () -> bool
+    def broadcasts_value?
+      return false if observable_name == PayloadBroadcast::REVISION_OBSERVABLE
+
+      actor_class = SolidObjects.registry.fetch(instance.actor_type)
+      actor_class.definition.broadcasts_observable_value?(observable_name)
+    end
   end
 end

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

@@ -113,7 +113,7 @@ The supervisor starts configured worker, effect, reminder, and broadcast thread
 
 ### Effect worker
 
-An effect worker claims due effect rows through the database coordination adapter, invokes a registered handler outside a database transaction, then records success or retryable failure. The handler receives the effect UUID as its idempotency key. Optional outcome messages are normal actor mailbox messages.
+An effect worker claims due effect rows through the database coordination adapter, invokes a registered handler outside a database transaction, then records success or retryable failure. The handler receives the effect UUID as its idempotency key. Optional outcome messages are normal actor mailbox messages and receive the effect ID, originally staged arguments, and result or error.
 
 ### Reminder scheduler
 
@@ -169,7 +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; it is not independently persisted.
+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:
 

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/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

data/docs/dashboard.md

@@ -0,0 +1,200 @@
+# Operator dashboard
+
+`SolidObjects::Web` is a Rack application that shows what the actor runtime is
+doing: instances and their state, the mailbox, reminders, effects, broadcasts,
+dead letters, and the registered processes. It reads the same tables the
+runtime writes, so it needs no separate store and no agent.
+
+It is deliberately not loaded by `require "solid_objects"`. A worker process
+must not carry a web stack, and an application that never mounts the dashboard
+must not pay for it.
+
+## Mounting
+
+```ruby
+# config/routes.rb
+require "solid_objects/web"
+
+Rails.application.routes.draw do
+  mount SolidObjects::Web => "/solid_objects/dashboard"
+end
+```
+
+Mount it inside the application routes so the Rails session middleware runs
+first. The dashboard needs a Rack session for CSRF protection and refuses a
+state changing request without one.
+
+The dashboard and the engine are separate mounts. Mount the engine as well if
+the application uses reactive ERB, and give each one its own path:
+
+```ruby
+mount SolidObjects::Engine => "/solid_objects"
+mount SolidObjects::Web => "/solid_objects/dashboard"
+```
+
+In a bare Rack application, supply the session middleware yourself:
+
+```ruby
+use Rack::Session::Cookie, secret: ENV.fetch("SESSION_SECRET"), same_site: true
+run SolidObjects::Web
+```
+
+## Authorization
+
+Every page asks `configuration.authorize_administration` before its handler
+runs. That policy denies by default, so a mount alone exposes nothing. A route
+declared without a policy raises at load time, which is why a new page cannot
+reach the actor tables before an application has said who may read it.
+
+The block receives the route's own action and resource:
+
+| Page | `action` | `resource` | `resource_id` |
+| --- | --- | --- | --- |
+| Dashboard, `GET /stats`, `HEAD /` | `index` | `dashboard` | none |
+| Instance list | `index` | `instances` | none |
+| Instance detail | `show` | `instances` | instance id |
+| Pause an instance | `pause` | `instances` | instance id |
+| Resume an instance | `resume` | `instances` | instance id |
+| Mailbox | `index` | `messages` | none |
+| Message detail | `show` | `messages` | message id |
+| Reminders | `index` | `reminders` | none |
+| Effects | `index` | `effects` | none |
+| Broadcasts | `index` | `broadcasts` | none |
+| Dead letter list | `index` | `dead_letters` | none |
+| Dead letter detail | `show` | `dead_letters` | dead letter id |
+| Retry a dead letter | `retry` | `dead_letters` | dead letter id |
+| Processes | `index` | `processes` | none |
+
+`authorization_context:` is the request object. It answers `request`,
+`session`, and `env`, so a policy can read the signed-in operator the same way
+a controller does:
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.authorize_administration = lambda do |action:, authorization_context:, **|
+    return false unless authorization_context.respond_to?(:session)
+
+    operator = Operator.find_by(id: authorization_context.session[:operator_id])
+    return false unless operator&.administrator?
+
+    action == "index" || action == "show" || operator.may_write_runtime?
+  end
+end
+```
+
+The command line reaches the same policy with `{ source: "cli" }` rather than
+a request, which is why the example checks what the context answers before
+reading a session from it.
+
+## Pages
+
+**Dashboard.** Totals per subsystem, the registered processes, and the most
+recent dead letters. The summary bar appears on every page and can poll
+`GET /stats` for the same numbers; nothing else on the page refreshes, because
+a table that reloads under an operator who is reading it is worse than a stale
+one.
+
+**Instances.** Filter by actor type and by an actor id substring. Each row
+shows the lease state: `idle`, `activated`, `expired`, or `paused`. The detail
+page shows committed state, the ready and claimed mailbox, message history,
+reminders, effects, broadcasts, and dead letters for that identity.
+
+**Mailbox.** The ready and claimed messages across every identity, oldest
+first. Mailbox lag on the summary bar is the age of the oldest message that is
+already due, which is how far behind the workers are.
+
+**Reminders, effects, broadcasts, processes.** Status filtered lists.
+
+## Charts
+
+The dashboard draws three charts: instances per actor type, mailbox depth, and
+a stacked view of effects, broadcasts, and reminders by status. Each canvas
+carries its own numbers in a `data-chart-values` attribute, so the page needs
+no inline script and no request to draw. Mailbox depth and the status chart
+redraw when the Live poller reports new totals, because `/stats` already
+carries those numbers. The instance chart does not: `/stats` does not group by
+actor type, and adding that would put a `GROUP BY` on every poll.
+
+Chart.js comes from a CDN with a subresource integrity hash, so a compromised
+CDN cannot substitute other code, and the CDN host is the only external origin
+the content security policy names.
+
+A deployment with no outbound network access should vendor the file:
+
+```ruby
+SolidObjects::Web.chart_library_url = "/javascripts/chart.umd.min.js"
+SolidObjects::Web.chart_library_integrity = nil
+```
+
+A path below the mount is served from the dashboard's own asset directory and
+needs no policy exception. Setting the URL to `nil` renders the dashboard
+without charts and names no external origin at all.
+
+Set these before the first request. The middleware stack and the compiled
+templates are built once and cached.
+
+**Dead letters.** The exception, its message, and its backtrace, with a retry
+button.
+
+## Actions
+
+The dashboard changes only two things.
+
+**Retry a dead letter** goes through `SolidObjects.dead_letters.retry`, which
+enqueues the original operation under an idempotency key. Pressing it twice
+produces one message rather than two.
+
+A retry re-enters the mailbox, which refuses work the runtime cannot accept: an
+actor class that no longer exists, a full mailbox, a payload over the cap. The
+dashboard renders the dead letter again with the reason and a 422 status,
+rather than failing the request.
+
+**Pause an instance** sets `paused_at`, and the activation manager stops
+claiming that identity. Two consequences matter:
+
+- A pass already in flight finishes its turn. Pause is not a stop.
+- A synchronous caller waiting on a paused instance times out rather than
+  receiving a result, because nothing will execute its message.
+
+Resume clears the column and the mailbox drains in sequence order.
+
+## Extensions
+
+An extension adds pages by declaring routes on the application class. Its
+routes carry an authorization policy like every other route:
+
+```ruby
+module Tenants
+  def self.registered(application)
+    application.get "/tenants", policy: { action: "index", resource: "tenants" } do
+      @tenants = Tenant.order(:name)
+      erb(:tenants)
+    end
+  end
+end
+
+SolidObjects::Web.register(
+  Tenants,
+  tab: "Tenants",
+  path: "/tenants",
+  views: File.expand_path("../web/views", __dir__)
+)
+```
+
+A registered view directory is searched before the packaged one, so an
+application can replace a single page without forking the gem. A template
+reads its arguments from `locals`, and a replacement `layout.erb` renders the
+page it wraps with `locals.fetch(:content)`.
+
+Add Rack middleware in front of the dashboard with `SolidObjects::Web.use`,
+for example to require HTTP basic authentication in an environment that has no
+session-backed operator.
+
+## Cost
+
+The summary bar issues one grouped count per subsystem on every page, and each
+list page counts its own relation to page it. That is a fixed set of indexed
+aggregate queries, not a scan proportional to actor traffic, but it is not
+free: do not put the dashboard behind an uptime monitor that loads the whole
+page on an interval. `HEAD /` exists for that. It touches one table and
+returns no body.

data/docs/database-schema.md

@@ -92,10 +92,11 @@ Status/availability/ID drives delivery; completion/ID drives cleanup.
 ### `broadcasts`
 
 Durable observable-change outbox. The unique message/observable key prevents
-duplicate rows for one actor turn. Rows contain the observable JSON value and
-message/instance references used to derive invalidation metadata, never
-personalized rendered HTML. Claim and delivery indexes support retries and
-cleanup.
+duplicate rows for one actor turn. Rows contain `{}` for the default
+invalidation-only observable, or the observable JSON value after an explicit
+`broadcast: :value` opt-in, plus message/instance references used to derive
+invalidation metadata, never personalized rendered HTML. Claim and delivery
+indexes support retries and cleanup.
 
 ### `dead_letters`
 

data/docs/development.md

@@ -65,6 +65,18 @@ assert_equal "completed", message.status
 Pass `roles: [:actors]` when a test intentionally wants to leave outboxes or
 reminders pending.
 
+Rails time travel does not move the database clock used by reminder claims. Run
+future reminders against an explicit test instant instead of updating runtime
+rows or sleeping:
+
+```ruby
+assert_equal 1, run_due_reminders(now: 5.minutes.from_now)
+assert_equal 1, drain_solid_objects(roles: [ :actors ])
+```
+
+The explicit instant controls due selection and recurring schedule advancement.
+Claim timestamps and stale-process recovery still use database time.
+
 `SolidObjects::TestHelper.reset_actors!` is also available for explicit suite
 boundaries. It deletes every actor-owned row itself rather than deleting actor
 instances and letting the database cascade remove the rest: SQLite has to be

data/docs/realtime.md

@@ -13,12 +13,19 @@
 <% end %>
 ```
 
-Every observable gets a stable opaque DOM ID. Multiple values share the one
-actor subscription and Action Cable multiplexes actor subscriptions over the
-browser's physical WebSocket.
+Every value-broadcast observable gets a stable opaque DOM ID. Multiple values
+share the one actor subscription and Action Cable multiplexes actor
+subscriptions over the browser's physical WebSocket.
 
 Scalar observable calls such as `cart.items_count` render stable `<span>`
-targets. Their broadcast remains a direct escaped text replacement.
+targets. Their broadcast remains a direct escaped text replacement, and their
+declaration must explicitly opt in with `broadcast: :value`:
+
+```ruby
+observable :items_count, broadcast: :value do
+  items.sum { |item| item.fetch("quantity") }
+end
+```
 
 A reactive component declares one or more explicit observable dependencies.
 `actor.component(:summary, observes: ...)` resolves the host partial by
@@ -65,6 +72,27 @@ listed in `observes:` raises `UnknownComponentDependency`. This keeps
 invalidation correct and prevents a partial from silently depending on state
 that cannot wake it.
 
+Observables are invalidation-only by default. Their values never enter the
+durable outbox or Action Cable frame, so the ordinary declaration is the safe
+choice for component dependencies:
+
+```ruby
+observable :player_one do
+  player_in_seat(1)
+end
+```
+
+The runtime still compares the value around each successful turn and uses a
+change to refresh components, but stores `{}` and renders no scalar Turbo
+replacement. An invalidation-only observable therefore cannot be used as a
+scalar value such as `actor.player_one`. The component endpoint reads the
+latest committed value and authorizes it again; subscriber-specific state
+belongs in `broadcast_payload`.
+
+Use `broadcast: :value` only for a shared projection that may be stored and
+sent to every subscriber that passes `authorize_subscription`. Authorization
+to the actor stream is not a per-viewer projection.
+
 ```erb
 <ul>
   <% actor.recent_messages.each do |message| %>
@@ -416,7 +444,9 @@ component key, locals, or DOM ID.
 ## Broadcast durability
 
 The actor's fenced commit compares observables before and after the turn and
-inserts one broadcast row per changed value. The actor state, monotonic
+inserts one broadcast row per changed observable. Invalidation-only
+observables, the default, store `{}`. Observables declared with
+`broadcast: :value` store the changed JSON value. The actor state, monotonic
 `state_revision`, message completion, and broadcast rows commit atomically. A
 rolled-back or fenced-out turn therefore cannot invalidate a component.
 
@@ -456,8 +486,8 @@ response revision fencing.
 ## Cost model
 
 The durable row cost is unchanged: one broadcast row per changed observable,
-containing its JSON value and the message/instance references needed to derive
-invalidation metadata. No rendered document is stored. Each affected component
+containing either its JSON value or an empty invalidation marker plus the
+message/instance references needed to derive invalidation metadata. No rendered document is stored. Each affected component
 adds one authorized GET and one partial render per non-coalesced state
 revision. A repeated keyed component adds one GET and render per key. Signed
 locals increase page and Cable subscription bytes but do not create durable