solid_objects 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e251e3648db71bc5e325e1d8a20be55f927ca08208052acebd973eb78e15497
-  data.tar.gz: 9362cf7145cb58c02273411dc619a775d7693d238d3f2212d7c4f6336abc30cb
+  metadata.gz: 6996e5e1ea8fa47b59b66cb6ed0f72e28d1673c2da5697e5507873db55f0b7ff
+  data.tar.gz: edb728dd6427ca4a1486dc791816b7a3ab8d3bdf822992c27d3800ab925c120e
 SHA512:
-  metadata.gz: de728511cbd174ba841030f3e29e3dd4245ccd4dd8168523bf132100a8e4ee0c14f02781bf0b29c08a184f3688708f01d8227662068e6a25ebac1ea2b948c72e
-  data.tar.gz: a9d34e2ae1defd4288bd9322b3d717ae1fbcc99836f96d76ae2a09d62355e17349089e4b53d9febcefe98aa788c5753b5abcbeee1c9dce08e6968b38297f336e
+  metadata.gz: 888370023e0d24e18eda279862a01a31b8583fccc5913fae571fa76d4001de1f408b22e7c3242c23975f01aeb293c47bd9314d94d98177e99c353fb78796caaa
+  data.tar.gz: 130982ddf19508a6268ae7356ac6249cd8efcc10cc29dd5c13e5cd865322540deabae688e511825a3a92bdc6bfe6314cf9f003d3ec2f4d273d968668438a1588

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.6.0 - 2026-08-09
+
+- Add `broadcast_payload`, an actor DSL for sending one personalized JSON state
+  payload over the actor stream a page already has open. The block runs once per
+  subscriber with that subscriber's authorization context, so private state
+  never crosses sessions. Payloads carry actor identity and the monotonic state
+  revision, and both the channel and the browser drop stale revisions. Subscribe
+  with `solid_object room, payloads: :playmat_state` and handle the
+  `solid-objects:payload` DOM event. ERB component refreshes remain the default
+  and are unchanged. A mutation that changes payload state without changing a
+  declared observable still invalidates subscribers, through a revision-only
+  broadcast that carries no observable value to the browser.
+
+## 0.5.2 - 2026-08-09
+
+- Read the database clock once per transaction instead of once per step, and
+  resolve the SQLite busy wait from configuration instead of querying the
+  connection for it. A synchronous call now issues 49 database queries instead
+  of 66, which matters most on PostgreSQL and MySQL where every query is a
+  network round trip.
+- Apply every migration in the benchmark harness. It applied only the initial
+  migration, so the `state_revision` column added in 0.4.0 was missing, every
+  message failed at commit, and the synchronous benchmarks timed out.
+
 ## 0.5.1 - 2026-08-07
 
 - Restore the SQLite busy wait that a synchronous invocation suspends for its

data/app/assets/javascripts/solid_objects/state_payload.js

@@ -0,0 +1,69 @@
+const deliveredRevisions = new Map()
+
+class SolidObjectsPayloadElement extends HTMLElement {
+  connectedCallback() {
+    if (this.dataset.started === "true") return
+
+    this.dataset.started = "true"
+    this.deliver()
+  }
+
+  deliver() {
+    try {
+      const name = this.dataset.name
+      const revision = revisionFor(this)
+      const scope = this.closest("[id]")
+      if (!name || !revision || !scope) return
+
+      const key = `${scope.id}:${name}`
+      if (!newerRevision(revision, deliveredRevisions.get(key))) return
+
+      const payload = JSON.parse(this.textContent)
+      deliveredRevisions.set(key, revision)
+      scope.dispatchEvent(
+        new CustomEvent("solid-objects:payload", {
+          bubbles: true,
+          detail: {
+            name,
+            instanceId: revision[0],
+            revision: revision[1],
+            payload
+          }
+        })
+      )
+    } catch {
+      this.dispatchEvent(
+        new CustomEvent("solid-objects:payload-error", {
+          bubbles: true,
+          detail: { reason: "invalid_payload" }
+        })
+      )
+    } finally {
+      this.remove()
+    }
+  }
+}
+
+function newerRevision(candidate, current) {
+  if (!current) return true
+
+  return candidate[0] > current[0] ||
+    (candidate[0] === current[0] && candidate[1] > current[1])
+}
+
+function revisionFor(element) {
+  const revision = element.dataset.revision
+  if (!revision) return
+
+  const values = revision.split(":").map(Number)
+  if (
+    values.length !== 2 ||
+    values.some((value) => !Number.isSafeInteger(value) || value < 0)
+  ) return
+
+  return values
+}
+
+if (!customElements.get("solid-objects-payload")) {
+  customElements.define("solid-objects-payload", SolidObjectsPayloadElement)
+}

data/app/helpers/solid_objects/actor_helper.rb

@@ -2,8 +2,9 @@
 
 module SolidObjects
   module ActorHelper
-    # @rbs (Reference, ?authorization_context: untyped) { (ActorView) -> untyped } -> untyped
-    def solid_object(reference, authorization_context: self, &block)
+    # @rbs (Reference, ?authorization_context: untyped, ?payloads: untyped) { (ActorView) -> untyped } -> untyped
+    def solid_object(reference, authorization_context: self, payloads: nil, &block)
+      payload_names = Array(payloads).map(&:to_s).uniq.presence
       actor = ActorView.new(
         reference:,
         view_context: self,
@@ -13,7 +14,8 @@ module SolidObjects
       subscription_data = {
         token: StreamToken.generate(
           reference,
-          observables: actor.scalar_observable_names
+          observables: actor.scalar_observable_names,
+          payloads: payload_names
         )
       }
       if actor.component_tokens.any?
@@ -30,10 +32,17 @@ module SolidObjects
           data: { turbo_track: "reload" }
         )
       end
+      payload_client = if payload_names
+        javascript_include_tag(
+          "solid_objects/state_payload",
+          type: "module",
+          data: { turbo_track: "reload" }
+        )
+      end
 
       content_tag(
         :div,
-        safe_join([ refresh_client, subscription, content ].compact),
+        safe_join([ refresh_client, payload_client, subscription, content ].compact),
         id: DomIdentity.scope(reference)
       )
     end

data/benchmark/support.rb

@@ -228,7 +228,9 @@ module SolidObjectsBenchmark
     # @rbs () -> void
     def migrate
       require_relative "../db/migrate/20260805000000_create_solid_objects_tables"
+      require_relative "../db/migrate/20260806000000_add_state_revision_to_solid_objects_instances"
       CreateSolidObjectsTables.new.migrate(:up)
+      AddStateRevisionToSolidObjectsInstances.new.migrate(:up)
     end
 
     # @rbs () -> void

data/docs/benchmarks.md

@@ -41,6 +41,13 @@ scenario used four worker threads.
 | Synchronous latency | p50 1.8 ms, p95 25.6 ms, p99 156.2 ms |
 | Activation reuse | 98.0%, four activations for 200 messages |
 | Queries for one message turn | 29 |
+| Queries for one synchronous call | 49 |
+
+A synchronous call costs far more queries than a worker turn because the caller
+also registers or heartbeats its caller process, claims the activation, and
+observes the result. Query count, not query time, dominates synchronous latency
+on a networked database: measured locally against SQLite, database time is
+roughly 5% of a call and the remaining 95% is Ruby.
 
 The difference between the SQLite development result and the MySQL adoption
 result is why Solid Objects does not publish one latency promise. Network

data/docs/realtime.md

@@ -110,6 +110,93 @@ applications discover the namespaced engine asset. Applications created with
 explicitly serve the module. Turbo's normal morph rules still apply; use
 `data-turbo-permanent` for elements that must never be changed.
 
+## Personalized state payloads
+
+Reactive ERB components cost one browser request per changed component. When a
+single actor mutation changes several components, an application pays several
+round trips for one logical update. A payload broadcast collapses that into one
+message on the stream the page already has open.
+
+Declare the payload on the actor. The block receives the actor and the
+subscriber's authorization context, and it runs **once per subscriber**, so two
+sessions watching the same actor never see each other's private state:
+
+```ruby
+class PlaymatRoom < SolidObjects::Actor
+  actor_type "playmat_room"
+
+  attribute :hands, default: -> { {} }
+  attribute :turn, default: 1
+
+  observable :turn
+
+  broadcast_payload :playmat_state do |room, authorization_context|
+    {
+      "turn" => room.turn,
+      "hand" => room.hands.fetch(authorization_context.session_id, [])
+    }
+  end
+end
+```
+
+Subscribe the scope to it:
+
+```erb
+<%= solid_object room, payloads: :playmat_state do |actor| %>
+  <div data-playmat></div>
+<% end %>
+```
+
+Handle it with any JavaScript. The gem dispatches a DOM event and requires no
+framework:
+
+```javascript
+document.addEventListener("solid-objects:payload", (event) => {
+  const { name, revision, payload } = event.detail
+  if (name !== "playmat_state") return
+
+  renderPlaymat(payload)
+})
+```
+
+### What the protocol guarantees
+
+The payload travels as a Turbo Stream element on the existing actor stream, so
+applications do not run a second WebSocket system. Each message carries the
+actor identity plus the `instance_id` and monotonic `state_revision` that fence
+component refreshes, and both the channel and the browser drop a payload that
+is not newer than the last one delivered for that scope and name. A reconnecting
+client receives the current payload on subscribe.
+
+Authorization is the same `authorize_query` boundary that components use, called
+with the payload name and the subscriber's Cable connection. A subscriber that
+fails the check is skipped rather than served a partial payload, and the payload
+name is signed into the stream token, so a browser cannot ask for a payload the
+server did not offer.
+
+Payload blocks read committed actor state through the same snapshot components
+use. They cannot write application records, and the return value must be a JSON
+object or array so the wire format stays inspectable.
+
+### mtg-playmat before and after
+
+Before, one mutation that touched three observables produced three refresh
+elements and three HTTP requests:
+
+```
+commit -> 3 Action Cable messages -> 3 GET /solid_objects/components -> 3 renders
+```
+
+After, the same mutation delivers one personalized payload and the page renders
+once:
+
+```
+commit -> 1 Action Cable message -> 0 HTTP requests -> 1 render
+```
+
+Components remain the default. An actor with no `broadcast_payload` and a scope
+with no `payloads:` option behave exactly as before.
+
 ## Authorization
 
 The HTML contains a signed actor identity token. Signing prevents modification;

data/lib/solid_objects/actor.rb

@@ -57,6 +57,13 @@ module SolidObjects
         definition.add_observable(name, block)
       end
 
+      # @rbs (Symbol | String) { (untyped, untyped) -> untyped } -> ActorDefinition::Handler
+      def broadcast_payload(name, &block)
+        raise InvalidActor, "payload broadcasts require a block" unless block
+
+        definition.add_payload_broadcast(name, block)
+      end
+
       # @rbs (?Integer) -> Integer
       def state_version(version = nil)
         definition.set_state_version(version) if version

data/lib/solid_objects/actor_channel.rb

@@ -19,7 +19,9 @@ module SolidObjects
 
       @reference = Reference.new(actor_type:, actor_id:)
       @scalar_observables = identity["observables"]
+      @payload_names = identity["payloads"]
       validate_scalar_observables!
+      validate_payload_names!
       @component_subscriptions = ComponentSubscriptions.parse(
         params["components"],
         reference:
@@ -36,6 +38,7 @@ module SolidObjects
         )
       end
       refresh_outdated_components(snapshot)
+      transmit_state_payloads(snapshot)
     rescue KeyError,
       JSON::ParserError,
       InvalidStreamToken,
@@ -46,14 +49,20 @@ module SolidObjects
 
     private
 
-    attr_reader :reference, :component_subscriptions, :scalar_observables
+    attr_reader :reference,
+      :component_subscriptions,
+      :scalar_observables,
+      :payload_names
 
     # @rbs (String) -> void
     def receive_broadcast(stream)
       invalidation = TurboStreamRenderer.invalidation(stream)
-      if !invalidation ||
-          scalar_observables.nil? ||
-          scalar_observables.include?(invalidation.fetch("observable_name"))
+      revision_only = invalidation &&
+        invalidation.fetch("observable_name") == PayloadBroadcast::REVISION_OBSERVABLE
+      if !revision_only &&
+          (!invalidation ||
+            scalar_observables.nil? ||
+            scalar_observables.include?(invalidation.fetch("observable_name")))
         transmit stream
       end
       return unless invalidation
@@ -61,6 +70,48 @@ module SolidObjects
       component_subscriptions
         .refreshes_for(invalidation)
         .each { |refresh| transmit refresh }
+      transmit_state_payloads(ActorSnapshot.new(reference))
+    end
+
+    # @rbs (ActorSnapshot) -> void
+    def transmit_state_payloads(snapshot)
+      return if payload_names.nil? || payload_names.empty?
+      return unless newer_payload_revision?(snapshot)
+
+      payload_names.each do |name|
+        payload = PayloadBroadcast.new(
+          snapshot:,
+          name:,
+          authorization_context: connection
+        ).call
+        transmit TurboStreamRenderer.state_payload(payload)
+      rescue Unauthorized
+        next
+      end
+      @payload_revision = [ snapshot.instance_id, snapshot.revision ]
+    end
+
+    # @rbs (ActorSnapshot) -> bool
+    def newer_payload_revision?(snapshot)
+      current = @payload_revision
+      return true unless current
+
+      (current <=> [ snapshot.instance_id, snapshot.revision ]) == -1
+    end
+
+    # @rbs () -> void
+    def validate_payload_names!
+      return unless payload_names
+
+      broadcasts = SolidObjects
+        .registry
+        .fetch(reference.actor_type)
+        .definition
+        .payload_broadcasts
+      unknown = payload_names.find { |name| !broadcasts.key?(name.to_sym) }
+      return unless unknown
+
+      raise InvalidStreamToken, "unknown payload broadcast #{unknown.inspect}"
     end
 
     # @rbs (ActorSnapshot) -> void

data/lib/solid_objects/actor_definition.rb

@@ -9,6 +9,7 @@ module SolidObjects
     # @rbs @messages: Hash[Symbol, Handler]
     # @rbs @queries: Hash[Symbol, Handler]
     # @rbs @observables: Hash[Symbol, Handler]
+    # @rbs @payload_broadcasts: Hash[Symbol, Handler]
     # @rbs @state_version: Integer
     # @rbs @state_migrations: Array[StateMigration]
     # @rbs @activation_hooks: Array[Proc]
@@ -20,6 +21,7 @@ module SolidObjects
       :messages,
       :queries,
       :observables,
+      :payload_broadcasts,
       :state_version,
       :state_migrations,
       :activation_hooks,
@@ -31,6 +33,7 @@ module SolidObjects
       @messages = {}
       @queries = {}
       @observables = {}
+      @payload_broadcasts = {}
       @state_version = 1
       @state_migrations = []
       @activation_hooks = []
@@ -83,6 +86,21 @@ module SolidObjects
       end
     end
 
+    # @rbs (Symbol | String, Proc) -> Handler
+    def add_payload_broadcast(name, block)
+      payload_name = name.to_sym
+      if payload_broadcasts.key?(payload_name)
+        raise InvalidActor, "#{payload_name.inspect} payload broadcast is already defined"
+      end
+      unless payload_name.to_s.match?(/\A[a-zA-Z0-9_]+\z/)
+        raise InvalidActor, "payload broadcast names may contain only letters, digits, and underscores"
+      end
+
+      Handler.new(name: payload_name, block:).tap do |handler|
+        payload_broadcasts[payload_name] = handler
+      end
+    end
+
     # @rbs (Class) -> ActorDefinition
     def synchronize_instance_messages(actor_class)
       names = actor_message_method_names(actor_class)
@@ -149,6 +167,7 @@ module SolidObjects
         copy.instance_variable_set(:@messages, messages.dup)
         copy.instance_variable_set(:@queries, queries.dup)
         copy.instance_variable_set(:@observables, observables.dup)
+        copy.instance_variable_set(:@payload_broadcasts, payload_broadcasts.dup)
         copy.instance_variable_set(:@state_version, state_version)
         copy.instance_variable_set(:@state_migrations, state_migrations.dup)
         copy.instance_variable_set(:@activation_hooks, activation_hooks.dup)

data/lib/solid_objects/database_adapter.rb

@@ -4,6 +4,9 @@ require "time"
 
 module SolidObjects
   class DatabaseAdapter
+    TRANSACTION_CLOCK = :solid_objects_transaction_clock
+    TRANSACTION_CLOCK_SCOPE = :solid_objects_transaction_clock_scope
+
     class << self
       # @rbs (untyped) -> DatabaseAdapter
       def for(connection)
@@ -46,10 +49,9 @@ module SolidObjects
 
     # @rbs () -> Time
     def database_now
-      value = with_connection do |connection|
-        connection.select_value("SELECT #{current_time_expression}")
-      end
-      value.is_a?(Time) ? value.utc : Time.parse("#{value} UTC").utc
+      return read_database_now unless ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK_SCOPE]
+
+      ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK] ||= read_database_now
     end
 
     # @rbs () { () -> untyped } -> untyped
@@ -70,7 +72,7 @@ module SolidObjects
         with_transaction_deadline(connection) do
           connection.transaction(requires_new: true) do
             configure_transaction_deadline(connection)
-            block.call
+            with_transaction_clock { block.call }
           end
         end
       end
@@ -91,6 +93,27 @@ module SolidObjects
 
     attr_reader :connection_pool, :fixed_connection
 
+    # @rbs () { () -> untyped } -> untyped
+    def with_transaction_clock
+      return yield if ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK_SCOPE]
+
+      ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK_SCOPE] = true
+      begin
+        yield
+      ensure
+        ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK_SCOPE] = false
+        ActiveSupport::IsolatedExecutionState[TRANSACTION_CLOCK] = nil
+      end
+    end
+
+    # @rbs () -> Time
+    def read_database_now
+      value = with_connection do |connection|
+        connection.select_value("SELECT #{current_time_expression}")
+      end
+      value.is_a?(Time) ? value.utc : Time.parse("#{value} UTC").utc
+    end
+
     # @rbs (untyped) { () -> untyped } -> untyped
     def with_transaction_deadline(_connection)
       yield

data/lib/solid_objects/database_adapters/sqlite.rb

@@ -80,13 +80,13 @@ module SolidObjects
 
       # @rbs (untyped) -> Hash[Symbol, untyped]?
       def restorable_busy_wait(connection)
-        pragma_timeout = connection.select_value("PRAGMA busy_timeout").to_i
-        return { pragma_timeout: } if pragma_timeout.positive?
-
         handler_timeout = configured_busy_handler_timeout(connection)
-        return nil unless handler_timeout
+        return { handler_timeout: } if handler_timeout
+
+        pragma_timeout = connection.select_value("PRAGMA busy_timeout").to_i
+        return nil unless pragma_timeout.positive?
 
-        { pragma_timeout:, handler_timeout: }
+        { pragma_timeout: }
       end
 
       # @rbs (untyped, Hash[Symbol, untyped]) -> void

data/lib/solid_objects/errors.rb

@@ -43,6 +43,12 @@ module SolidObjects
   class UnknownComponent < Error
   end
 
+  class UnknownPayloadBroadcast < Error
+  end
+
+  class InvalidPayloadBroadcast < Error
+  end
+
   class UnknownComponentDependency < Error
   end
 

data/lib/solid_objects/executor.rb

@@ -27,7 +27,7 @@ module SolidObjects
       result = invoke_actor(message_context)
       ensure_query_did_not_mutate_state!(state_before)
       observable_changes = changed_observables(observables_before, actor.observable_values)
-      complete(result, observable_changes)
+      complete(result, observable_changes, state_changed: actor.state.to_h != state_before)
       true
     rescue LostActivation
       raise
@@ -75,8 +75,8 @@ module SolidObjects
       end
     end
 
-    # @rbs (untyped, Hash[String, untyped]) -> void
-    def complete(result, observable_changes)
+    # @rbs (untyped, Hash[String, untyped], state_changed: bool) -> void
+    def complete(result, observable_changes, state_changed:)
       serialized_state = Serialization.dump(
         actor.state.to_h,
         max_bytes: SolidObjects.configuration.max_state_bytes
@@ -111,7 +111,12 @@ module SolidObjects
         enqueued_effects.concat(
           enqueue_actor_messages(locked_message, instance, outbound_message_intents)
         )
-        enqueue_broadcasts(locked_message, instance, observable_changes)
+        enqueue_broadcasts(
+          locked_message,
+          instance,
+          observable_changes,
+          state_changed:
+        )
         claimed_message.destroy!
       end
 
@@ -249,9 +254,14 @@ module SolidObjects
       end
     end
 
-    # @rbs (Message, Instance, Hash[String, untyped]) -> void
-    def enqueue_broadcasts(locked_message, instance, observable_changes)
-      observable_changes.each do |observable_name, value|
+    # @rbs (Message, Instance, Hash[String, untyped], state_changed: bool) -> void
+    def enqueue_broadcasts(locked_message, instance, observable_changes, state_changed:)
+      broadcasts = observable_changes
+      if broadcasts.empty? && state_changed && payload_broadcasts?
+        broadcasts = { PayloadBroadcast::REVISION_OBSERVABLE => {} }
+      end
+
+      broadcasts.each do |observable_name, value|
         Broadcast.create!(
           message: locked_message,
           instance:,
@@ -266,6 +276,11 @@ module SolidObjects
       end
     end
 
+    # @rbs () -> bool
+    def payload_broadcasts?
+      actor.class.definition.payload_broadcasts.any?
+    end
+
     # @rbs (Exception) -> void
     def fail_message(error)
       error_details = serialized_error(error)

data/lib/solid_objects/payload_broadcast.rb

@@ -0,0 +1,67 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class PayloadBroadcast
+    MAXIMUM_PAYLOAD_BYTES = 1_048_576
+    REVISION_OBSERVABLE = "solid_objects.revision"
+
+    # @rbs @snapshot: ActorSnapshot
+    # @rbs @name: String
+    # @rbs @authorization_context: untyped
+
+    attr_reader :name
+
+    # @rbs (snapshot: ActorSnapshot, name: String, authorization_context: untyped) -> void
+    def initialize(snapshot:, name:, authorization_context:)
+      @snapshot = snapshot
+      @name = name
+      @authorization_context = authorization_context
+    end
+
+    # @rbs () -> Hash[String, untyped]
+    def call
+      handler = snapshot.actor_class.definition.payload_broadcasts[name.to_sym]
+      raise UnknownPayloadBroadcast, "unknown payload broadcast #{name.inspect}" unless handler
+
+      authorize!
+      {
+        "actor_type" => snapshot.reference.actor_type,
+        "actor_id" => snapshot.reference.actor_id,
+        "name" => name,
+        "instance_id" => snapshot.instance_id,
+        "revision" => snapshot.revision,
+        "payload" => rendered_payload(handler)
+      }
+    end
+
+    private
+
+    attr_reader :snapshot, :authorization_context
+
+    # @rbs (ActorDefinition::Handler) -> untyped
+    def rendered_payload(handler)
+      payload = Serialization.dump(
+        handler.block.call(snapshot.actor, authorization_context),
+        max_bytes: MAXIMUM_PAYLOAD_BYTES
+      )
+      return payload if payload.is_a?(Hash) || payload.is_a?(Array)
+
+      raise InvalidPayloadBroadcast,
+        "payload broadcast #{name.inspect} must return a JSON object or array"
+    end
+
+    # @rbs () -> void
+    def authorize!
+      authorized = SolidObjects.configuration.authorize_query.call(
+        actor_type: snapshot.reference.actor_type,
+        actor_id: snapshot.reference.actor_id,
+        message_name: name,
+        arguments: {},
+        authorization_context:
+      )
+      return if authorized
+
+      raise Unauthorized, "actor payload broadcast is not authorized"
+    end
+  end
+end

data/lib/solid_objects/stream_token.rb

@@ -9,13 +9,14 @@ module SolidObjects
 
     module_function
 
-    # @rbs (Reference, ?observables: Array[String]?) -> String
-    def generate(reference, observables: nil)
+    # @rbs (Reference, ?observables: Array[String]?, ?payloads: Array[String]?) -> String
+    def generate(reference, observables: nil, payloads: nil)
       identity = {
         "actor_type" => reference.actor_type,
         "actor_id" => reference.actor_id
       }
       identity["observables"] = observables if observables
+      identity["payloads"] = payloads if payloads
       validate_identity!(identity)
       verifier.generate(identity, purpose: PURPOSE)
     end
@@ -36,21 +37,27 @@ module SolidObjects
         raise InvalidStreamToken, "invalid actor stream token"
       end
 
-      observables = identity["observables"]
-      return identity unless observables
+      validate_names!(identity["observables"], "observables")
+      validate_names!(identity["payloads"], "payloads")
+      identity
+    end
+
+    # @rbs (untyped, String) -> void
+    def validate_names!(names, label)
+      return unless names
 
-      valid = observables.is_a?(Array) &&
-        observables.length <= MAXIMUM_OBSERVABLES &&
-        observables.uniq.length == observables.length &&
-        observables.all? do |observable|
-          observable.is_a?(String) &&
-            observable.match?(/\A[a-zA-Z0-9_]+\z/)
+      valid = names.is_a?(Array) &&
+        names.length <= MAXIMUM_OBSERVABLES &&
+        names.uniq.length == names.length &&
+        names.all? do |name|
+          name.is_a?(String) && name.match?(/\A[a-zA-Z0-9_]+\z/)
         end
-      return identity if valid
+      return if valid
 
-      raise InvalidStreamToken, "invalid actor stream observables"
+      raise InvalidStreamToken, "invalid actor stream #{label}"
     end
     private_class_method :validate_identity!
+    private_class_method :validate_names!
 
     # @rbs () -> ActiveSupport::MessageVerifier
     def verifier

data/lib/solid_objects/turbo_stream_renderer.rb

@@ -16,11 +16,15 @@ module SolidObjects
         actor_type: broadcast.instance.actor_type,
         actor_id: broadcast.instance.actor_id
       )
-      stream = observable_value(
-        reference,
-        broadcast.observable_name,
-        broadcast.value
-      )
+      stream = if broadcast.observable_name == PayloadBroadcast::REVISION_OBSERVABLE
+        ""
+      else
+        observable_value(
+          reference,
+          broadcast.observable_name,
+          broadcast.value
+        )
+      end
       metadata = Base64.urlsafe_encode64(
         JSON.generate(
           "instance_id" => broadcast.instance_id,
@@ -50,6 +54,19 @@ module SolidObjects
       %(<turbo-stream action="replace" target="#{target}"><template><turbo-frame id="#{target}" src="#{source}" data-solid-objects-revision="#{revision_value}" data-solid-objects-refresh="replace"></turbo-frame></template></turbo-stream>)
     end
 
+    # @rbs (Hash[String, untyped]) -> String
+    def state_payload(payload)
+      reference = Reference.new(
+        actor_type: payload.fetch("actor_type"),
+        actor_id: payload.fetch("actor_id")
+      )
+      scope = DomIdentity.scope(reference)
+      name = ERB::Util.html_escape(payload.fetch("name"))
+      revision = "#{payload.fetch("instance_id")}:#{payload.fetch("revision")}"
+      body = ERB::Util.html_escape(JSON.generate(payload.fetch("payload")))
+      %(<turbo-stream action="append" target="#{scope}"><template><solid-objects-payload data-name="#{name}" data-revision="#{revision}">#{body}</solid-objects-payload></template></turbo-stream>)
+    end
+
     # @rbs (String) -> Hash[String, untyped]?
     def invalidation(stream)
       encoded = stream[INVALIDATION_PATTERN, 1]

data/lib/solid_objects/version.rb

@@ -1,5 +1,5 @@
 # rbs_inline: enabled
 
 module SolidObjects
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/lib/solid_objects.rb

@@ -40,6 +40,7 @@ require "solid_objects/component_registration"
 require "solid_objects/component_subscriptions"
 require "solid_objects/component_view"
 require "solid_objects/component_renderer"
+require "solid_objects/payload_broadcast"
 require "solid_objects/state_snapshot"
 require "solid_objects/actor_view"
 require "solid_objects/actor_channel"

data/sig/generated/helpers/solid_objects/actor_helper.rbs

@@ -2,7 +2,7 @@
 
 module SolidObjects
   module ActorHelper
-    # @rbs (Reference, ?authorization_context: untyped) { (ActorView) -> untyped } -> untyped
-    def solid_object: (Reference, ?authorization_context: untyped) { (ActorView) -> untyped } -> untyped
+    # @rbs (Reference, ?authorization_context: untyped, ?payloads: untyped) { (ActorView) -> untyped } -> untyped
+    def solid_object: (Reference, ?authorization_context: untyped, ?payloads: untyped) { (ActorView) -> untyped } -> untyped
   end
 end

data/sig/generated/lib/solid_objects/actor.rbs

@@ -90,6 +90,9 @@ module SolidObjects
     # @rbs (Symbol | String) ?{ () -> untyped } -> ActorDefinition::Handler
     def self.observable: (Symbol | String) ?{ () -> untyped } -> ActorDefinition::Handler
 
+    # @rbs (Symbol | String) { (untyped, untyped) -> untyped } -> ActorDefinition::Handler
+    def self.broadcast_payload: (Symbol | String) { (untyped, untyped) -> untyped } -> ActorDefinition::Handler
+
     # @rbs (?Integer) -> Integer
     def self.state_version: (?Integer) -> Integer
 

data/sig/generated/lib/solid_objects/actor_channel.rbs

@@ -13,9 +13,20 @@ module SolidObjects
 
     attr_reader scalar_observables: untyped
 
+    attr_reader payload_names: untyped
+
     # @rbs (String) -> void
     def receive_broadcast: (String) -> void
 
+    # @rbs (ActorSnapshot) -> void
+    def transmit_state_payloads: (ActorSnapshot) -> void
+
+    # @rbs (ActorSnapshot) -> bool
+    def newer_payload_revision?: (ActorSnapshot) -> bool
+
+    # @rbs () -> void
+    def validate_payload_names!: () -> void
+
     # @rbs (ActorSnapshot) -> void
     def refresh_outdated_components: (ActorSnapshot) -> void
 

data/sig/generated/lib/solid_objects/actor_definition.rbs

@@ -42,6 +42,8 @@ module SolidObjects
 
     @state_version: Integer
 
+    @payload_broadcasts: Hash[Symbol, Handler]
+
     @observables: Hash[Symbol, Handler]
 
     @queries: Hash[Symbol, Handler]
@@ -58,6 +60,8 @@ module SolidObjects
 
     attr_reader observables: untyped
 
+    attr_reader payload_broadcasts: untyped
+
     attr_reader state_version: untyped
 
     attr_reader state_migrations: untyped
@@ -81,6 +85,9 @@ module SolidObjects
     # @rbs (Symbol | String, Proc?) -> Handler
     def add_observable: (Symbol | String, Proc?) -> Handler
 
+    # @rbs (Symbol | String, Proc) -> Handler
+    def add_payload_broadcast: (Symbol | String, Proc) -> Handler
+
     # @rbs (Class) -> ActorDefinition
     def synchronize_instance_messages: (Class) -> ActorDefinition
 

data/sig/generated/lib/solid_objects/database_adapter.rbs

@@ -2,6 +2,10 @@
 
 module SolidObjects
   class DatabaseAdapter
+    TRANSACTION_CLOCK: ::Symbol
+
+    TRANSACTION_CLOCK_SCOPE: ::Symbol
+
     # @rbs (untyped) -> DatabaseAdapter
     def self.for: (untyped) -> DatabaseAdapter
 
@@ -42,6 +46,12 @@ module SolidObjects
 
     attr_reader fixed_connection: untyped
 
+    # @rbs () { () -> untyped } -> untyped
+    def with_transaction_clock: () { () -> untyped } -> untyped
+
+    # @rbs () -> Time
+    def read_database_now: () -> Time
+
     # @rbs (untyped) { () -> untyped } -> untyped
     def with_transaction_deadline: (untyped) { () -> untyped } -> untyped
 

data/sig/generated/lib/solid_objects/errors.rbs

@@ -43,6 +43,12 @@ module SolidObjects
   class UnknownComponent < Error
   end
 
+  class UnknownPayloadBroadcast < Error
+  end
+
+  class InvalidPayloadBroadcast < Error
+  end
+
   class UnknownComponentDependency < Error
   end
 

data/sig/generated/lib/solid_objects/executor.rbs

@@ -30,8 +30,8 @@ module SolidObjects
     # @rbs (Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
     def changed_observables: (Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
 
-    # @rbs (untyped, Hash[String, untyped]) -> void
-    def complete: (untyped, Hash[String, untyped]) -> void
+    # @rbs (untyped, Hash[String, untyped], state_changed: bool) -> void
+    def complete: (untyped, Hash[String, untyped], state_changed: bool) -> void
 
     # @rbs (Array[Actor::CommitActionIntent]) -> void
     def execute_commit_actions: (Array[Actor::CommitActionIntent]) -> void
@@ -51,8 +51,11 @@ module SolidObjects
     # @rbs (Message, Instance, Array[Actor::OutboundMessageIntent]) -> Array[Effect]
     def enqueue_actor_messages: (Message, Instance, Array[Actor::OutboundMessageIntent]) -> Array[Effect]
 
-    # @rbs (Message, Instance, Hash[String, untyped]) -> void
-    def enqueue_broadcasts: (Message, Instance, Hash[String, untyped]) -> void
+    # @rbs (Message, Instance, Hash[String, untyped], state_changed: bool) -> void
+    def enqueue_broadcasts: (Message, Instance, Hash[String, untyped], state_changed: bool) -> void
+
+    # @rbs () -> bool
+    def payload_broadcasts?: () -> bool
 
     # @rbs (Exception) -> void
     def fail_message: (Exception) -> void

data/sig/generated/lib/solid_objects/payload_broadcast.rbs

@@ -0,0 +1,35 @@
+# Generated from lib/solid_objects/payload_broadcast.rb with RBS::Inline
+
+module SolidObjects
+  class PayloadBroadcast
+    MAXIMUM_PAYLOAD_BYTES: ::Integer
+
+    REVISION_OBSERVABLE: ::String
+
+    @snapshot: ActorSnapshot
+
+    @name: String
+
+    @authorization_context: untyped
+
+    attr_reader name: untyped
+
+    # @rbs (snapshot: ActorSnapshot, name: String, authorization_context: untyped) -> void
+    def initialize: (snapshot: ActorSnapshot, name: String, authorization_context: untyped) -> void
+
+    # @rbs () -> Hash[String, untyped]
+    def call: () -> Hash[String, untyped]
+
+    private
+
+    attr_reader snapshot: untyped
+
+    attr_reader authorization_context: untyped
+
+    # @rbs (ActorDefinition::Handler) -> untyped
+    def rendered_payload: (ActorDefinition::Handler) -> untyped
+
+    # @rbs () -> void
+    def authorize!: () -> void
+  end
+end

data/sig/generated/lib/solid_objects/stream_token.rbs

@@ -6,8 +6,8 @@ module SolidObjects
 
     MAXIMUM_OBSERVABLES: ::Integer
 
-    # @rbs (Reference, ?observables: Array[String]?) -> String
-    def self?.generate: (Reference, ?observables: Array[String]?) -> String
+    # @rbs (Reference, ?observables: Array[String]?, ?payloads: Array[String]?) -> String
+    def self?.generate: (Reference, ?observables: Array[String]?, ?payloads: Array[String]?) -> String
 
     # @rbs (String) -> Hash[String, untyped]
     def self?.verify: (String) -> Hash[String, untyped]
@@ -15,6 +15,9 @@ module SolidObjects
     # @rbs (Hash[String, untyped]) -> Hash[String, untyped]
     def self?.validate_identity!: (Hash[String, untyped]) -> Hash[String, untyped]
 
+    # @rbs (untyped, String) -> void
+    def self?.validate_names!: (untyped, String) -> void
+
     # @rbs () -> ActiveSupport::MessageVerifier
     def self?.verifier: () -> ActiveSupport::MessageVerifier
 

data/sig/generated/lib/solid_objects/turbo_stream_renderer.rbs

@@ -15,6 +15,9 @@ module SolidObjects
     # @rbs (ComponentRegistration, Integer, Integer) -> String
     def self?.component_refresh: (ComponentRegistration, Integer, Integer) -> String
 
+    # @rbs (Hash[String, untyped]) -> String
+    def self?.state_payload: (Hash[String, untyped]) -> String
+
     # @rbs (String) -> Hash[String, untyped]?
     def self?.invalidation: (String) -> Hash[String, untyped]?
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-08 00:00:00.000000000 Z
+date: 2026-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -263,6 +263,7 @@ files:
 - README.md
 - Rakefile
 - app/assets/javascripts/solid_objects/component_refresh.js
+- app/assets/javascripts/solid_objects/state_payload.js
 - app/controllers/solid_objects/application_controller.rb
 - app/controllers/solid_objects/components_controller.rb
 - app/controllers/solid_objects/dead_letters_controller.rb
@@ -382,6 +383,7 @@ files:
 - lib/solid_objects/mailbox.rb
 - lib/solid_objects/message_pruner.rb
 - lib/solid_objects/message_reference.rb
+- lib/solid_objects/payload_broadcast.rb
 - lib/solid_objects/process_pruner.rb
 - lib/solid_objects/process_registry.rb
 - lib/solid_objects/reference.rb
@@ -452,6 +454,7 @@ files:
 - sig/generated/lib/solid_objects/mailbox.rbs
 - sig/generated/lib/solid_objects/message_pruner.rbs
 - sig/generated/lib/solid_objects/message_reference.rbs
+- sig/generated/lib/solid_objects/payload_broadcast.rbs
 - sig/generated/lib/solid_objects/process_pruner.rbs
 - sig/generated/lib/solid_objects/process_registry.rbs
 - sig/generated/lib/solid_objects/reference.rbs