solid_objects 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e89f40dd095ec1d8934ff47872f3638ca441203186a7a1562dc9f603c939150
-  data.tar.gz: 23389e8737fcbfc816ca41aedf56f4b83baa6769fc2c54f6d9ca3622c67ca135
+  metadata.gz: 8dc01a4c7b7f44d7dbd68b1194abd64a2c5515d5280a1e9cae15b119ff18508c
+  data.tar.gz: 68099ea645dff1d976f9aeda77d79d04ed8280e18bfc6d4235daca972ffafad4
 SHA512:
-  metadata.gz: d28e8e826c045dc546a13eb34631c692281b82b10a55205f0f6b3a17b77a1a2144bbfb786c69c86d701d42d356c65da4c26d7dd2f25a5538f9743e4405aa53b1
-  data.tar.gz: 34c89447e1592ea056d511db1fbf01de898c1563c34616a7b80058b0c1bb649b3a4e01cf7f1fad6de35bedc82e484c0a8c96b21aa0be1d959b94c3492fd3d3c4
+  metadata.gz: 335cec6b8f87328e9a88eee32bbd8aaca5b019cb0ef76dfa70f5efa261afb81a2a034d3bc6a11189f22c4809583d9cce1538c6ecb1ff8cc8319c1d195fec8295
+  data.tar.gz: 445c227d5badd737cb44f9b44b87917b73c3e2a55a66acb6a4cd1fe09a39febda314f00188cd35eabc70acef5d5b95503c3cedf5c35632e22948fa62667a62db

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # 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

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
@@ -1082,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/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

@@ -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:
 

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, or
-`{}` for an invalidation-only observable, plus 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/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,16 +72,12 @@ listed in `observes:` raises `UnknownComponentDependency`. This keeps
 invalidation correct and prevents a partial from silently depending on state
 that cannot wake it.
 
-Observable values are shared projections. By default, each changed value is
-stored in the broadcast outbox and can be sent as a scalar Turbo replacement to
-every subscriber that passes `authorize_subscription`. Authorization to the
-actor stream is not a per-viewer projection.
-
-For a component dependency whose value must never enter the durable outbox or
-Action Cable frame, declare it invalidation-only:
+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, broadcast: :invalidation do
+observable :player_one do
   player_in_seat(1)
 end
 ```
@@ -86,6 +89,10 @@ 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| %>
@@ -437,8 +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 observable. Value-broadcast observables
-store the changed JSON value; invalidation-only observables store `{}`. 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.
 

data/docs/roadmap.md

@@ -24,10 +24,11 @@
   listed here while broken in that worker: the scheduler reached a constant the
   caller path happened to load, so reminders never fired in production and
   every in-process test still passed
-- Durable value or invalidation-only observable broadcasts, scalar Turbo
-  replacement, keyed ERB components, signed component locals, and authorized
-  replace or morph refresh. Invalidation-only observables retain component
-  change detection while storing and broadcasting no projected value
+- Durable invalidation-only observable broadcasts by default, explicit
+  `broadcast: :value` scalar Turbo replacement, keyed ERB components, signed
+  component locals, and authorized replace or morph refresh. Default
+  observables retain component change detection while storing and broadcasting
+  no projected value
 - 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
@@ -107,8 +108,25 @@
   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.
+- Administration: `SolidObjects::Web` is a mountable Rack dashboard covering
+  instances, mailbox, reminders, effects, broadcasts, dead letters, and
+  processes, with actor-type and actor-id filtering, status filters, paging, a
+  polled stats endpoint, Chart.js charts, and extension registration. The chart
+  library is fetched from a CDN with a subresource integrity hash, which a
+  deployment without outbound network access must replace with a vendored copy
+  or turn off. Every route declares its
+  own administration policy and a route declared without one raises at load
+  time, so the deny-by-default posture is enforced by construction rather than
+  by remembering to add a check. It changes only two things: an idempotent dead
+  letter retry and instance pause/resume. What does not exist is audit records
+  of who pressed what, and bulk-safe tools: retry is one dead letter at a time,
+  because `DeadLetterManager` exposes no bulk operation. Pause is an operator
+  brake and not a stop, since a pass already in flight finishes its turn and a
+  synchronous caller waiting on a paused instance times out. The page cost was
+  reasoned about rather than measured: the summary bar issues a fixed set of
+  indexed aggregate queries per page, which is why `HEAD /` exists for uptime
+  monitors, but no dashboard latency has been benchmarked against a large
+  table.
 
 ## Next milestones
 

data/docs/security.md

@@ -36,13 +36,13 @@ Opaque stream and DOM names reduce accidental disclosure but do not replace
 authorization. Signed stream tokens are readable by their recipient and prove
 integrity only.
 
-Every normal observable value is stored in the broadcast outbox and can reach
-every subscriber that passes `authorize_subscription` for the actor. Never put
-credentials, session identifiers, private cards, hidden library order, or any
-other subscriber-specific state in a value-broadcast observable. Declare a
-component dependency with `broadcast: :invalidation` when only change metadata
-may cross the shared stream, or use `broadcast_payload` for a projection that
-must be computed separately for each authorized connection.
+Observables are invalidation-only by default, so their durable rows and shared
+actor stream carry no projected value. `broadcast: :value` deliberately stores
+the value in the broadcast outbox and may send it to every subscriber that
+passes `authorize_subscription` for the actor. Never opt credentials, session
+identifiers, private cards, hidden library order, or any other
+subscriber-specific state into value broadcasting. Use `broadcast_payload` for
+a projection that must be computed separately for each authorized connection.
 
 ## Serialization
 

data/examples/application/README.md

@@ -10,8 +10,8 @@ key. The chat actor also gives every submitted chat message a caller-generated
 message ID and checks that ID in durable actor state, because actor handlers may
 be redelivered.
 
-The views demonstrate scalar observable replacement and a live chat-message
-ERB component. The chat component receives `recent_messages` as an ordinary
-Ruby array, rerenders its `<ol>` after committed changes, and refreshes through
-the authenticated host request context. Turbo append intents remain roadmap
-work.
+The views demonstrate explicit `broadcast: :value` scalar replacement and a
+default invalidation-only chat-message ERB component. The chat component
+receives `recent_messages` as an ordinary Ruby array, rerenders its `<ol>` after
+committed changes, and refreshes through the authenticated host request
+context. Turbo append intents remain roadmap work.

data/examples/application/app/actors/chat_room_actor.rb

@@ -6,7 +6,7 @@ class ChatRoomActor < SolidObjects::Actor
   attribute :members, default: -> { [] }
   attribute :recent_messages, default: -> { [] }
 
-  observable :presence do
+  observable :presence, broadcast: :value do
     members.length
   end
 

data/examples/application/app/actors/shopping_cart_actor.rb

@@ -5,11 +5,11 @@ class ShoppingCartActor < SolidObjects::Actor
   attribute :checkout_status, default: "open"
   attribute :payment_id
 
-  observable :items_count do
+  observable :items_count, broadcast: :value do
     items.sum { |item| item.fetch("quantity") }
   end
 
-  observable :subtotal_cents do
+  observable :subtotal_cents, broadcast: :value do
     items.sum do |item|
       item.fetch("quantity") * item.fetch("unit_price_cents")
     end

data/lib/solid_objects/actor.rb

@@ -53,7 +53,7 @@ module SolidObjects
       end
 
       # @rbs (Symbol | String, ?broadcast: Symbol) ?{ () -> untyped } -> ActorDefinition::Handler
-      def observable(name, broadcast: :value, &block)
+      def observable(name, broadcast: :invalidation, &block)
         definition.add_observable(name, block, broadcast:)
       end