solid_objects 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48689af6e9b4f08415ddfd549a99d4e7e667e67db5aa4e92bc0052a6d97f51af
-  data.tar.gz: 82dc95dc346daf7260356996bfadc99c9c8dd713f2c0fa8c5d8f5efe7859021a
+  metadata.gz: 557108141818714af50bfee19acda22c9243482e976b50329e5e234aed6d9adb
+  data.tar.gz: fe525288022e4bb0630e60bc7ec949e2f61d1ad152fadcaccaeaa41bd1a0376e
 SHA512:
-  metadata.gz: d3a4ce2860cca8656919193b2a9bb6b2c2367552653af106db5fd065bd2bf3c7339a543c5b1bc1fdf1bb7d322e88639a6f20cdba2b5cf551b406e629e6d31598
-  data.tar.gz: '086652b090e80b0c6830b269e8857ef6de1944b2c2ab145340eeb4a8ba97a26875b9a612c5105ae46bff7362477fe20c3abde837aa4b87d27f5fb91bf19e316e'
+  metadata.gz: e4414b1f2e0d47f95f9307fec6140894bcd8ebcab6dbdc20f54155c332dea76de2728ca7b0bf71bc13c978f2494e059f2099986757c3b933296d460a2bec7a65
+  data.tar.gz: 6e807551d58c7d87465bc55b460386f5b9617e36021ddbdfdcbfd25aac31d9c48a7166a818f5a39be3f52eb6a7cb63efd74223a0512fb7a53dce7c55a2c23ca8

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.4.0 - 2026-08-06
+
+- Add dependency-driven live ERB components with request-time authorization,
+  conventional partial resolution, revision fencing, refresh coalescing, and
+  reconnect convergence without broadcasting personalized HTML.
+- Persist a monotonic state revision for secure component refresh ordering.
+- Retry SQLite synchronous lock contention in Ruby so a native busy wait
+  cannot starve the thread holding the database lock.
+- Allow maintainers to dispatch CI manually when a push webhook is dropped.
+
 ## 0.3.0 - 2026-08-06
 
 - Reject application-record writes from actor handlers and provide registered

data/README.md

@@ -74,6 +74,7 @@ tested, but the project does not yet claim production readiness. See
 - [Cloudflare Durable Objects for Rails](#cloudflare-durable-objects-for-rails)
 - [Reactive ERB](#reactive-erb)
 - [Installation](#installation)
+- [Upgrading](#upgrading)
 - [Worker requirements](#worker-requirements)
 - [Defining an actor](#defining-an-actor)
 - [Actor identity](#actor-identity)
@@ -173,42 +174,105 @@ rolled-back state change cannot leak into the page.
 Define an observable:
 
 ```ruby
-class ShoppingCart < SolidObjects::Actor
-  attribute :items, default: -> { [] }
+class ChatRoom < SolidObjects::Actor
+  attribute :recent_messages, default: -> { [] }
+  attribute :status, default: "open"
 
-  observable :items_count do
-    items.sum { |item| item.fetch("quantity") }
+  observable :message_count do
+    recent_messages.length
   end
+
+  observable :recent_messages
+  observable :status
 end
 ```
 
-Render it:
+Scalar observables remain stable `<span>` targets:
+
+```erb
+<%= solid_object @room, authorization_context: current_user do |room| %>
+  Messages: <%= room.message_count %>
+<% end %>
+```
+
+Reactive components rerender a host ERB partial when one of their explicit
+dependencies changes:
 
 ```erb
-<%= solid_object current_cart do |cart| %>
-  Cart items: <%= cart.items_count %>
+<%= solid_object @room, authorization_context: current_user do |room| %>
+  <%= room.component :messages, observes: :recent_messages %>
+  <%= room.component :presence, observes: %i[recent_messages status] %>
 <% end %>
 ```
 
-That template provides initial server rendering, a stable opaque DOM target,
-and live Turbo replacements after committed actor turns. One `solid_object`
-block makes one Action Cable subscription for all values inside it, and Action
-Cable multiplexes subscriptions over the browser's WebSocket.
+`room.component(:messages)` resolves only
+`actors/chat_room/_messages`. Its partial receives `actor` and
+`authorization_context` locals:
+
+```erb
+<ul>
+  <% actor.recent_messages.each do |message| %>
+    <li><%= message.fetch("body") %></li>
+  <% end %>
+</ul>
+```
+
+Declared observables are deeply frozen ordinary Ruby values inside a
+component. Arrays support loops, hashes support ordinary lookup, conditionals
+work normally, and ERB still escapes user strings. A reactive component cannot
+read `actor.state`, access an undeclared observable, or choose a dynamic
+partial path.
+
+That template provides initial server rendering, stable opaque DOM targets,
+and live updates after committed actor turns. One `solid_object` block makes
+one Action Cable subscription for all scalar values and components inside it,
+and Action Cable multiplexes subscriptions over the browser's WebSocket.
 
 No client-side state store, custom Stimulus controller, channel class, manual
 broadcast, or one-WebSocket-per-value setup is required. Signed stream tokens
-protect integrity, an application policy authorizes every subscription,
-broadcasts are delivered from a durable outbox, and reconnecting clients
-refresh from current actor state.
+protect integrity, not access. Initial rendering authorizes with the
+`authorization_context` passed to `solid_object`; Cable authorizes with its
+connection; every component refresh authorizes again with a request-specific
+context:
 
-`cart.component(:summary)` supports initial rendering of
-`actors/shopping_cart/_summary`. Durable live component replacement and
-Turbo append actions are roadmap work; observable replacement is the live path
-implemented today.
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.component_authorization_context = ->(controller:) { Current.user }
+end
+```
+
+The durable outbox stores one row per changed observable, never personalized
+HTML. Cable sends invalidation metadata over the shared actor stream, then a
+Turbo Frame requests the component with normal cookies. Only scalar targets
+that the server rendered into this `solid_object` scope are signed into its
+stream token and receive value payloads; component-only dependencies do not
+send their values to the browser. The endpoint renders the latest committed
+snapshot, returns `private, no-store`, and reauthorizes the component name plus
+every declared dependency. Two viewers can therefore receive different HTML
+for the same actor without sharing either projection.
+
+Reconnect compares the component's signed initial revision with the latest
+actor incarnation and state revision, then refreshes stale components. Cable
+coalesces several dependency changes from one actor turn into one component
+refresh and ignores older out-of-order invalidations. A newer invalidation
+replaces an in-flight frame, so its detached older response cannot overwrite
+newer state.
+
+Reactive components add no HTML to durable rows, but each affected component
+causes an authorized HTTP render. One actor turn still inserts one broadcast
+row per changed observable; several dependencies from that turn coalesce at
+the subscriber. Keep components bounded, declare only necessary dependencies,
+and use scalar observables for inexpensive single-value replacement.
 
 Reactive views require `turbo-rails` and a working Action Cable adapter in the
-host application. They are optional; the actor runtime itself does not depend
-on Turbo.
+host application. The Solid Objects engine must be mounted so its signed
+component endpoint is reachable. Reactive views are optional; the actor
+runtime itself does not depend on Turbo.
+
+```ruby
+# config/routes.rb
+mount SolidObjects::Engine => "/solid_objects"
+```
 
 ## Installation
 
@@ -274,6 +338,50 @@ can generate the gem RBI with:
 bundle exec tapioca gem solid_objects
 ```
 
+## Upgrading
+
+Review [CHANGELOG.md](CHANGELOG.md) for compatibility and deployment-order
+notes, then update the gem:
+
+```bash
+bundle update solid_objects
+```
+
+If the `Gemfile` pins an exact version, update that constraint first and run
+`bundle install`. Commit both `Gemfile.lock` and the copied Solid Objects
+migrations.
+
+Copy only migrations that the newer gem has added, migrate, and verify the
+installation:
+
+```bash
+bin/rails solid_objects:install:migrations
+bin/rails db:migrate
+bin/rails solid_objects:doctor
+```
+
+The migration task skips engine migrations already present in the application
+and gives new migrations host-specific timestamps. Inspect the resulting
+`db/migrate/*.solid_objects.rb` files before applying them. Do not rerun
+`generate solid_objects:install` during an upgrade because that also attempts
+to regenerate the application initializer.
+
+When Solid Objects uses a separate database configuration named `actors`, copy
+and run migrations through that database's configured migration path:
+
+```bash
+DATABASE=actors bin/rails solid_objects:install:migrations
+bin/rails db:migrate:actors
+bin/rails solid_objects:doctor
+```
+
+For production, back up the actor database and run new migrations before
+starting application or Solid Objects worker processes that require the new
+schema. Restart the web and Solid Objects worker fleet after the bundle and
+schema are current. For releases that change actor state versions, also follow
+the [state migration and rolling-deployment guide](docs/state-migrations.md);
+Rails schema migrations and actor state migrations are separate concerns.
+
 ## Worker requirements
 
 Synchronous actors can be adopted without adding a long-running process. Start
@@ -290,7 +398,7 @@ the runtime when the feature introduces asynchronous delivery or outboxes:
 | `emit` without an actor callback | Effect worker |
 | `emit` with success or failure callback | Effect worker and actor worker |
 | Actor-to-actor `async` or `send_to` | Effect worker and actor worker |
-| Observable Turbo updates | Broadcast worker, Action Cable, and the actor execution path |
+| Scalar or component Turbo updates | Broadcast worker, Action Cable, and the actor execution path |
 | Initial `solid_object` server render | No Solid Objects worker; normal Rails rendering |
 
 One command starts every Solid Objects role:
@@ -929,7 +1037,7 @@ See the [development guide](docs/development.md) and
 
 ## Status
 
-Implemented and tested in 0.3:
+Implemented and tested in 0.4:
 
 - Rails engine, install generator, migrations, and `solid_objects` executable;
 - actor registry, references, JSON state, and state migrations;
@@ -947,7 +1055,8 @@ Implemented and tested in 0.3:
 - one-shot and recurring per-actor reminders;
 - authorized actor destruction with fenced stale-write rejection and cascading
   durable-work cleanup;
-- durable observable broadcasts and authorized Action Cable refresh;
+- durable observable invalidations, scalar Turbo replacement, and authorized
+  request-time ERB component refresh;
 - process registration, heartbeats, caller shutdown, cleanup, and bounded
   message/process retention plus opt-in actor-instance expiration;
 - an opt-in Minitest helper for actor-state isolation and deterministic async
@@ -961,8 +1070,8 @@ Partially implemented:
   run periodic maintenance automatically;
 - cross-process wake-up uses polling; PostgreSQL notifications and optional
   Redis acceleration are not implemented;
-- live observable replacement works, while live component replacement and
-  Turbo append actions remain future work;
+- live observable and component replacement work, while Turbo append actions
+  remain future work;
 - local admission limits exist, but distributed rate limits and global
   admission control do not; and
 - administration views and pruning commands exist, but scheduled maintenance

data/app/controllers/solid_objects/components_controller.rb

@@ -0,0 +1,78 @@
+# rbs_inline: enabled
+
+require "action_controller/base"
+
+module SolidObjects
+  class ComponentsController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    # @rbs () -> void
+    def show
+      registration = ComponentRegistration.from_token(
+        params.require(:token)
+      )
+      requested_revision = requested_revision_key
+      snapshot = ActorSnapshot.new(registration.reference)
+      return head :conflict if newer_than_snapshot?(requested_revision, snapshot)
+
+      authorization_context = SolidObjects
+        .configuration
+        .component_authorization_context
+        .call(controller: self)
+      rendered = ComponentRenderer.new(
+        snapshot:,
+        component_name: registration.component_name,
+        dependencies: registration.dependencies,
+        view_context: component_view_context,
+        authorization_context:
+      ).call
+      response.headers["Cache-Control"] = "private, no-store"
+      render html: component_frame(registration, snapshot, rendered)
+    rescue Unauthorized
+      head :forbidden
+    rescue UnknownComponent
+      head :not_found
+    rescue ActionController::ParameterMissing,
+      ArgumentError,
+      InvalidComponentToken
+      head :bad_request
+    end
+
+    private
+
+    # @rbs () -> Array[Integer]
+    def requested_revision_key
+      instance_id = Integer(params.fetch(:instance_id), 10)
+      revision = Integer(params.fetch(:revision), 10)
+      raise ArgumentError if instance_id.negative? || revision.negative?
+
+      [ instance_id, revision ]
+    end
+
+    # @rbs (Array[Integer], ActorSnapshot) -> bool
+    def newer_than_snapshot?(requested_revision, snapshot)
+      (requested_revision <=> [ snapshot.instance_id, snapshot.revision ]) == 1
+    end
+
+    # @rbs () -> untyped
+    def component_view_context
+      if defined?(Rails) && Rails.application
+        prepend_view_path(*Rails.application.paths["app/views"].existent)
+      end
+
+      view_context.tap do |context|
+        context.extend(Rails.application.helpers) if defined?(Rails) && Rails.application
+      end
+    end
+
+    # @rbs (ComponentRegistration, ActorSnapshot, untyped) -> String
+    def component_frame(registration, snapshot, rendered)
+      target = DomIdentity.component(
+        registration.reference,
+        registration.component_name
+      )
+      revision = "#{snapshot.instance_id}:#{snapshot.revision}"
+      %(<turbo-frame id="#{target}" data-solid-objects-revision="#{revision}">#{rendered}</turbo-frame>).html_safe
+    end
+  end
+end

data/app/helpers/solid_objects/actor_helper.rb

@@ -9,11 +9,20 @@ module SolidObjects
         view_context: self,
         authorization_context:
       )
-      subscription = tag.turbo_cable_stream_source(
-        channel: "SolidObjects::ActorChannel",
-        token: StreamToken.generate(reference)
-      )
       content = capture(actor, &block)
+      subscription_attributes = {
+        channel: "SolidObjects::ActorChannel",
+        token: StreamToken.generate(
+          reference,
+          observables: actor.scalar_observable_names
+        )
+      }
+      if actor.component_tokens.any?
+        subscription_attributes[:data] = {
+          components: JSON.generate(actor.component_tokens)
+        }
+      end
+      subscription = tag.turbo_cable_stream_source(**subscription_attributes)
 
       content_tag(
         :div,

data/config/routes.rb

@@ -1,6 +1,7 @@
 # rbs_inline: enabled
 
 SolidObjects::Engine.routes.draw do
+  get :components, to: "components#show"
   resources :instances, only: %i[index show]
   resources :dead_letters, only: %i[index] do
     post :retry, on: :member

data/db/migrate/20260806000000_add_state_revision_to_solid_objects_instances.rb

@@ -0,0 +1,12 @@
+# rbs_inline: enabled
+
+class AddStateRevisionToSolidObjectsInstances < ActiveRecord::Migration[8.0]
+  # @rbs () -> void
+  def change
+    add_column SolidObjects.table_name(:instances),
+      :state_revision,
+      :bigint,
+      null: false,
+      default: 0
+  end
+end

data/docs/architecture.md

@@ -120,7 +120,11 @@ instance first prevents a claimed reminder from recreating a destroyed actor.
 
 ### Broadcast worker
 
-The broadcast worker claims committed observable-change rows, renders idempotent Turbo replacements, broadcasts to a signed actor stream, and records delivery. Current actor state remains the reconnect source of truth.
+The broadcast worker claims committed observable-change rows, renders
+idempotent scalar Turbo replacements with component invalidation metadata,
+broadcasts to a signed actor stream, and records delivery. It never renders
+personalized component HTML. Current actor state remains the reconnect and
+request-time component source of truth.
 
 ### Process registry
 
@@ -288,13 +292,14 @@ Successful completion uses one database transaction:
 3. Lock the durable message and verify its claimed membership belongs to that owner, activation token, and generation.
 4. Execute registered same-database commit actions.
 5. Update native JSON state and state version.
-6. Store the completion timestamp and result on the durable message and delete claimed membership.
-7. Insert staged effects.
-8. Insert or update staged reminders.
-9. Insert staged actor-message outbox rows.
-10. Insert changed-observable broadcast rows.
-11. Update actor last-used time.
-12. Commit.
+6. Advance the actor state revision to the completed message sequence.
+7. Store the completion timestamp and result on the durable message and delete claimed membership.
+8. Insert staged effects.
+9. Insert or update staged reminders.
+10. Insert staged actor-message outbox rows.
+11. Insert changed-observable broadcast rows.
+12. Update actor last-used time.
+13. Commit.
 
 Any lease or message predicate failure raises `LostActivation` and rolls back every item. The stale worker discards its in-memory activation.
 
@@ -460,25 +465,61 @@ Large repairs use `async(..., available_at:)` to spread work over an application
 
 ## Realtime integration
 
-`solid_object` performs an authorized state read for initial rendering and emits:
+`solid_object` performs an authorized state read for initial rendering and
+emits:
 
 - A stable scope DOM ID derived from actor type and a SHA-256 digest of actor ID
 - One Turbo Cable subscription element for the actor
 - Stable child target IDs for values and components
 - A signed actor token used by the channel subscription
+- Signed component registrations containing a conventional component name,
+  explicit observable dependencies, the initial actor incarnation/revision,
+  and a same-origin engine refresh path
 
 ```erb
 <%= solid_object current_cart do |cart| %>
   Cart items: <%= cart.items_count %>
-  <%= cart.component :summary %>
+  <%= cart.component :summary, observes: %i[items checkout_status] %>
 <% end %>
 ```
 
 The signed token proves integrity, not authorization. `ActorChannel#subscribed` verifies the token, resolves the registered actor type, invokes `authorize_subscription`, and only then streams.
 
-Broadcast replacements happen after the actor transaction commits because only a committed broadcast outbox row can be delivered. Multiple values share the same Action Cable connection and one actor subscription.
-
-Each channel subscription transmits current observable replacements before streaming future broadcasts, including after reconnect. Missing a broadcast therefore creates temporary staleness, not permanent divergence.
+Scalar observable calls remain direct escaped Turbo replacements. A reactive
+component resolves only `actors/<actor_class>/_<component>`, receives its
+declared observables as frozen Ruby values, and cannot read raw state or a
+dependency it did not declare. A static initial-only component can still use a
+server-selected explicit partial; a reactive component cannot.
+
+Broadcast replacements happen after the actor transaction commits because only
+a committed broadcast outbox row can be delivered. Multiple scalar values and
+components share the same Action Cable connection and one actor subscription.
+One outbox row still exists per changed observable.
+
+The shared stream contains invalidation metadata and scalar HTML only for the
+scalar targets signed into that scope's stream token. Component-only
+dependencies do not send their values to the browser, and the stream never
+contains personalized component HTML. For each subscription, `ActorChannel`
+matches the changed observable to registered component dependencies. It
+coalesces multiple dependencies at the same message sequence and drops older
+revision pairs. A component invalidation replaces its stable target with a
+Turbo Frame whose source is the signed engine endpoint.
+
+The browser then makes an ordinary cookie-bearing HTTP request. The engine
+controller derives a request-specific context through
+`component_authorization_context`, calls `authorize_query` for the component
+name and every declared dependency, renders the host partial from a new
+committed snapshot, and returns `private, no-store` HTML. Subscribers to the
+same actor can therefore receive different HTML without sharing it through
+Cable or the database.
+
+Each channel subscription transmits current scalar replacements and compares
+each component's signed initial revision against the latest committed
+`(instance_id, state_revision)` pair, including after reconnect. Missing a
+broadcast therefore creates temporary staleness, not permanent divergence.
+The instance primary key distinguishes destroy-and-recreate incarnations.
+Replacing the full frame on each newer invalidation detaches an older in-flight
+frame, preventing its slower response from replacing the current generation.
 
 ## Authorization
 
@@ -497,6 +538,11 @@ recognizable.
 
 No controller, channel, or administrative command treats an actor ID, message ID, request ID, or signed stream name as authorization.
 
+Initial component rendering, Cable subscription, and request-time component
+refresh deliberately use different authorization contexts. Signed component
+tokens constrain actor identity, component convention, dependencies, revision,
+and same-origin refresh path but never grant access.
+
 Actor IDs are bounded UTF-8 strings and never become constant names, SQL identifiers, file paths, or raw stream names.
 
 ## Serialization
@@ -639,7 +685,7 @@ PostgreSQL transaction-level advisory locks may be used for optional singleton m
 | Create actor and allocate message sequence | Instance insert/lock, sequence increment, durable message and ready-membership inserts |
 | Claim activation | Backend claim transaction, generation increment, owner and expiry |
 | Claim next message | Move ready membership to claimed membership conditioned on lease |
-| Successful message commit | Fenced state, durable message result, claimed-membership deletion, effects, reminders, actor outbox, broadcasts |
+| Successful message commit | Fenced state and monotonic revision, durable message result, claimed-membership deletion, effects, reminders, actor outbox, broadcasts |
 | Failed message attempt | Conditional error, claimed deletion, ready reinsertion or dead letter |
 | Renew or release lease | Conditional instance update |
 | Destroy actor | Instance identity lock and cascading delete of state, mailbox, reminders, and outboxes |
@@ -687,7 +733,7 @@ All backends use unique identity and sequence constraints, short transactions, a
 19. **How are state migrations performed?** Explicit one-step actor migrations on activation, persisted only with a successful fenced commit.
 20. **What happens during rolling deploys?** Newer state can make old workers incompatible; deploys must preserve backward readability or drain old workers.
 21. **How are subscriptions authorized?** Verify signed identity, resolve registered type, invoke host authorization, then stream.
-22. **How are lost broadcasts recovered?** Current-state refresh after reconnect; durable outbox retries server delivery.
+22. **How are lost broadcasts recovered?** Current-state scalar replacement and authorized component refresh after reconnect; durable outbox retries server delivery.
 23. **How are actor-to-actor cycles handled?** Synchronous actor waits are rejected; asynchronous request/result messages avoid call-stack cycles.
 24. **Which operations are transactional?** The transaction map above lists every atomic boundary. Actor code and external I/O are outside; registered same-pool commit actions execute inside the fenced state/message transaction.
 25. **Which guarantees depend on PostgreSQL?** None of the public semantics are PostgreSQL-only. PostgreSQL and MySQL depend on row-lock claiming; SQLite depends on serialized write transactions. Each backend's guarantee depends on its adapter-specific integration tests.

data/docs/authorization.md

@@ -10,7 +10,7 @@ intentionally inert until the host application defines its trust boundary.
 | Policy | Gates | Caller context | Risk if opened globally |
 | --- | --- | --- | --- |
 | `authorize_message` | Direct actor methods, explicit `sync` messages, and public `async` enqueue | Value passed as `authorization_context:`; often a user, service principal, or trusted internal marker | Anyone reaching the call site can mutate any known actor identity |
-| `authorize_query` | Attribute reads, declared queries, committed snapshots, observable reads, and component reads | Explicit call context or the Rails view context supplied by `solid_object` | Actor state can leak across users or tenants |
+| `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 |
@@ -20,6 +20,43 @@ invocation as a message or query. Internal reminder, effect-callback, and
 actor-to-actor deliveries come from
 already committed runtime rows and do not re-enter the public client policy.
 
+## Realtime authorization contexts
+
+Reactive components cross three Rails execution contexts and authorize at all
+three boundaries:
+
+1. `solid_object(..., authorization_context:)` uses the explicit Action View
+   render context for initial scalar and component reads.
+2. `ActorChannel` passes its authenticated `ActionCable::Connection` to
+   `authorize_subscription`.
+3. `ComponentsController` resolves a fresh context for the cookie-bearing HTTP
+   request and calls `authorize_query` for the component name and every
+   dependency.
+
+Configure the refresh resolver when the query policy expects a user or service
+principal rather than the engine controller:
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.component_authorization_context = lambda do |controller:|
+    Current.user
+  end
+end
+```
+
+Authentication middleware must populate `Current.user` for the refresh
+request. Do not copy an Action View object or Cable connection into the signed
+token. Those objects are request-specific and the token provides integrity,
+not authorization.
+
+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.
+
 ## A tenant-aware policy
 
 Pass the authenticated user as the call context:

data/docs/correctness.md

@@ -101,8 +101,8 @@ The following are atomic:
 - activation owner, expiration, and generation acquisition;
 - ready-to-claimed membership move and attempt increment;
 - state, state version, message result/completion, claimed deletion, effects,
-  same-database commit actions, reminders, outbound actor messages, and
-  observable broadcasts;
+  same-database commit actions, reminders, outbound actor messages, observable
+  broadcasts, and the monotonic actor state revision;
 - failed-attempt record plus ready reinsertion or dead letter;
 - effect completion plus its optional actor outcome message;
 - reminder occurrence enqueue plus reminder advancement; and
@@ -116,6 +116,32 @@ it is available only when Solid Objects and `ActiveRecord::Base` share one
 connection pool. Commit actions must contain only bounded database work.
 External I/O belongs in the effect outbox.
 
+## Reactive components
+
+A successful fenced turn advances `instances.state_revision` to that message's
+per-actor sequence and inserts changed-observable broadcast rows in the same
+transaction. A rollback, retryable handler failure, or lost activation advances
+neither. Component HTML is not durable and is never placed on the shared actor
+stream.
+
+Each component token signs the actor identity, conventional component name,
+explicit dependencies, initial instance ID and revision, and same-origin
+refresh path. The signature detects modification but grants no access. Initial
+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.
+
+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
+invalidation replaces the whole Turbo Frame generation. A response owned by
+the detached older frame cannot overwrite the current frame. Reconnect
+compares the component's signed initial pair with the current instance row and
+requests the latest committed snapshot when stale.
+
 ## Synchronous invocation
 
 A direct reference method or explicit `sync` call durably enqueues an ordinary

data/docs/database-schema.md

@@ -8,9 +8,15 @@ migrations load. No partial indexes are used.
 ### `instances`
 
 One row per `(actor_type, actor_id)`. Stores JSON state, state version,
-next-message sequence, activation owner/token/expiration/generation, pause
-state, and lifecycle timestamps. The owner/token pairing is constrained so one
-process row cannot make two concurrent activations appear identical.
+monotonic state revision, next-message sequence, activation
+owner/token/expiration/generation, pause state, and lifecycle timestamps. The
+owner/token pairing is constrained so one process row cannot make two
+concurrent activations appear identical.
+
+`state_revision` advances to the successful message sequence in the same
+fenced transaction as state and outboxes. Reactive components compare
+`(instance_id, state_revision)` so pruned message history cannot make revisions
+regress and destroy-and-recreate produces a new incarnation.
 
 Deleting an instance is the actor-incarnation boundary. Foreign keys cascade
 the delete through messages, ready and claimed memberships, reminders, effects,
@@ -85,8 +91,10 @@ 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. Claim and delivery indexes support retries
-and cleanup.
+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.
 
 ### `dead_letters`