fix: invalidate payloads on observable-free mutations

A message that changed state a payload reads without changing a declared observable enqueued no broadcast, so subscribers kept stale personalized state until an unrelated observable changed. Actors with payload broadcasts now enqueue a revision-only broadcast for those commits. The renderer emits invalidation metadata without an observable turbo stream, and the channel does not forward it, so no actor value reaches the browser through this path. Queries still enqueue nothing.

Author: cardmagic

CHANGELOG.md

@@ -9,7 +9,9 @@
   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.
+  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
 

lib/solid_objects/actor_channel.rb

@@ -57,9 +57,12 @@ def subscribed
     # @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

lib/solid_objects/executor.rb

@@ -27,7 +27,7 @@ def call
       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 @@ def changed_observables(before, after)
       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 @@ def complete(result, observable_changes)
         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 @@ def enqueue_actor_messages(locked_message, instance, intents)
       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 @@ def enqueue_broadcasts(locked_message, instance, observable_changes)
       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)

lib/solid_objects/payload_broadcast.rb

@@ -3,6 +3,7 @@
 module SolidObjects
   class PayloadBroadcast
     MAXIMUM_PAYLOAD_BYTES = 1_048_576
+    REVISION_OBSERVABLE = "solid_objects.revision"
 
     # @rbs @snapshot: ActorSnapshot
     # @rbs @name: String

lib/solid_objects/turbo_stream_renderer.rb

@@ -16,11 +16,15 @@ def observable(broadcast)
         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,

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

sig/generated/lib/solid_objects/payload_broadcast.rbs

@@ -4,6 +4,8 @@ module SolidObjects
   class PayloadBroadcast
     MAXIMUM_PAYLOAD_BYTES: ::Integer
 
+    REVISION_OBSERVABLE: ::String
+
     @snapshot: ActorSnapshot
 
     @name: String

test/integration/payload_broadcast_test.rb

@@ -150,6 +150,44 @@ def bump = self.value += 1
     assert_includes element, "Island"
   end
 
+  test "a mutation that changes no observable still invalidates the payload" do
+    reference = RoomActor.ref("table")
+    reference.advance_turn
+    SolidObjects::Broadcast.delete_all
+
+    reference.deal(session_id: "alice", cards: %w[Island])
+
+    broadcast = SolidObjects::Broadcast.order(:id).last
+    refute_nil broadcast, "a payload-only mutation must still reach subscribers"
+    assert_equal SolidObjects::PayloadBroadcast::REVISION_OBSERVABLE,
+      broadcast.observable_name
+  end
+
+  test "the revision invalidation carries no observable value to the browser" do
+    reference = RoomActor.ref("table")
+    reference.advance_turn
+    SolidObjects::Broadcast.delete_all
+    reference.deal(session_id: "alice", cards: %w[Black Lotus])
+
+    stream = SolidObjects::TurboStreamRenderer.observable(
+      SolidObjects::Broadcast.order(:id).last
+    )
+
+    refute_includes stream, "turbo-stream"
+    refute_includes stream, "Black Lotus"
+    refute_nil SolidObjects::TurboStreamRenderer.invalidation(stream)
+  end
+
+  test "a query does not invalidate the payload" do
+    reference = RoomActor.ref("table")
+    reference.deal(session_id: "alice", cards: %w[Island])
+    SolidObjects::Broadcast.delete_all
+
+    reference.turn
+
+    assert_equal 0, SolidObjects::Broadcast.count
+  end
+
   test "actors without a payload broadcast are unaffected" do
     plain = Class.new(SolidObjects::Actor) do
       actor_type "payload-none"