fix: secure realtime projections

Keep private observable values out of durable broadcasts while retaining\ncomponent invalidation. Align effect callbacks, rejection failures, and\nreminder testing with the cross-runtime contracts for version 0.12.1.

Author: cardmagic

CHANGELOG.md

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

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    solid_objects (0.12.0)
+    solid_objects (0.12.1)
       actioncable (>= 8.0)
       actionpack (>= 8.0)
       actionview (>= 8.0)
@@ -383,7 +383,7 @@ CHECKSUMS
   rubocop-rails-omakase (1.1.0) sha256=2af73ac8ee5852de2919abbd2618af9c15c19b512c4cfc1f9a5d3b6ef009109d
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
-  solid_objects (0.12.0)
+  solid_objects (0.12.1)
   sqlite3 (2.9.5-aarch64-linux-gnu) sha256=78075b6337d3d182c6d2b4691049ed45cd220826160c9ea18946bf6a1de200dc
   sqlite3 (2.9.5-aarch64-linux-musl) sha256=18c801185deb4adc01ddb281e8f672a39e3d1729979ca91e39439cd3eac0402d
   sqlite3 (2.9.5-arm-linux-gnu) sha256=1bdfca0c7d63998c60b0f4a8e3c8df2d33800ccc4abd2d612eddbbbc92a4c48b

README.md

@@ -205,6 +205,21 @@ 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:
+
+```ruby
+observable :player_one, broadcast: :invalidation do
+  player_in_seat(1)
+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.
+
 Component names can repeat when each instance has a stable key. Signed
 JSON-compatible locals let one conventional partial render the matching
 projection:
@@ -736,8 +751,8 @@ JSON-compatible details. The rejected message remains durable for audit, actor
 state is rolled back, and no later mailbox turn is blocked.
 
 `Rejected#code` is a `String`, even when `reject` receives a symbol. Codes must
-match `\A[a-z][a-z0-9_]*\z`; invalid codes raise `ArgumentError` when the
-handler calls `reject`.
+match `\A[A-Za-z_][A-Za-z0-9_]*\z`. Invalid codes raise
+`SolidObjects::InvalidRejectionCode` and fail the turn without retrying.
 
 ### Redelivery
 
@@ -819,11 +834,11 @@ def checkout(payment_id:, amount_cents:)
   )
 end
 
-def payment_succeeded(effect_id:, result:)
+def payment_succeeded(effect_id:, arguments:, result:)
   self.checkout_status = "paid"
 end
 
-def payment_failed(effect_id:, error:)
+def payment_failed(effect_id:, arguments:, error:)
   self.checkout_status = "failed"
 end
 ```
@@ -842,6 +857,10 @@ end
 
 The provider call can repeat if a process dies after external success but
 before recording completion. The stable effect ID is the idempotency key.
+Success callbacks receive `effect_id:`, the originally staged `arguments:`,
+and `result:`. Failure callbacks receive `effect_id:`, `arguments:`, and
+`error:`, so an actor can correlate concurrent effects without storing a
+separate callback ledger.
 
 ## Reminders
 

app/models/solid_objects/broadcast.rb

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

docs/architecture.md

@@ -113,7 +113,7 @@ The supervisor starts configured worker, effect, reminder, and broadcast thread
 
 ### Effect worker
 
-An effect worker claims due effect rows through the database coordination adapter, invokes a registered handler outside a database transaction, then records success or retryable failure. The handler receives the effect UUID as its idempotency key. Optional outcome messages are normal actor mailbox messages.
+An effect worker claims due effect rows through the database coordination adapter, invokes a registered handler outside a database transaction, then records success or retryable failure. The handler receives the effect UUID as its idempotency key. Optional outcome messages are normal actor mailbox messages and receive the effect ID, originally staged arguments, and result or error.
 
 ### Reminder scheduler
 
@@ -169,7 +169,8 @@ turn. `SolidObjects.mutable_copy` creates an independent mutable JSON value.
 `message` and `query` both execute as durable mailbox turns. A query may not
 mutate state. The executor detects query mutation and fails the message. An
 observable is a named projection of state used by server rendering and realtime
-updates; it is not independently persisted.
+updates. Its durable broadcast row stores the projected value by default;
+`broadcast: :invalidation` stores only an empty invalidation marker.
 
 Lifecycle hooks are deterministic local hooks:
 

docs/database-schema.md

@@ -92,8 +92,8 @@ Status/availability/ID drives delivery; completion/ID drives cleanup.
 ### `broadcasts`
 
 Durable observable-change outbox. The unique message/observable key prevents
-duplicate rows for one actor turn. Rows contain the observable JSON value and
-message/instance references used to derive invalidation metadata, never
+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.
 

docs/development.md

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

docs/realtime.md

@@ -65,6 +65,27 @@ 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:
+
+```ruby
+observable :player_one, broadcast: :invalidation do
+  player_in_seat(1)
+end
+```
+
+The runtime still compares the value around each successful turn and uses a
+change to refresh components, but stores `{}` and renders no scalar Turbo
+replacement. An invalidation-only observable therefore cannot be used as a
+scalar value such as `actor.player_one`. The component endpoint reads the
+latest committed value and authorizes it again; subscriber-specific state
+belongs in `broadcast_payload`.
+
 ```erb
 <ul>
   <% actor.recent_messages.each do |message| %>
@@ -416,7 +437,8 @@ component key, locals, or DOM ID.
 ## Broadcast durability
 
 The actor's fenced commit compares observables before and after the turn and
-inserts one broadcast row per changed value. The actor state, monotonic
+inserts one broadcast row per changed observable. Value-broadcast observables
+store the changed JSON value; invalidation-only observables store `{}`. The actor state, monotonic
 `state_revision`, message completion, and broadcast rows commit atomically. A
 rolled-back or fenced-out turn therefore cannot invalidate a component.
 
@@ -456,8 +478,8 @@ response revision fencing.
 ## Cost model
 
 The durable row cost is unchanged: one broadcast row per changed observable,
-containing its JSON value and the message/instance references needed to derive
-invalidation metadata. No rendered document is stored. Each affected component
+containing either its JSON value or an empty invalidation marker plus the
+message/instance references needed to derive invalidation metadata. No rendered document is stored. Each affected component
 adds one authorized GET and one partial render per non-coalesced state
 revision. A repeated keyed component adds one GET and render per key. Signed
 locals increase page and Cable subscription bytes but do not create durable

docs/roadmap.md

@@ -12,7 +12,8 @@
 - Bounded activation passes, idle cache, hot-actor yield, and process records
 - At-least-once retries, terminal domain rejection, strict poison ordering,
   dead letters, and tail retry
-- Transactional effects with success/failure actor messages
+- Transactional effects with success/failure actor messages carrying the
+  originally staged arguments for callback correlation
 - Actor-to-actor asynchronous outbox delivery. Effects and broadcasts use
   portable status rows with polling indexes and database check constraints on
   status, which works on all three adapters; a future version may add narrow
@@ -23,8 +24,10 @@
   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 observable invalidations, scalar Turbo replacement, keyed ERB
-  components, signed component locals, and authorized replace or morph refresh
+- 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
 - 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
@@ -45,7 +48,8 @@
 - Bounded message/process pruning, actor-type opt-in instance expiration,
   graceful caller shutdown, committed state snapshots, and an opt-in Minitest
   helper that clears every actor-owned table itself rather than relying on the
-  database cascade, which a host application may not enforce
+  database cascade, which a host application may not enforce, and runs due
+  reminders against an explicit test time without moving the database clock
 - Supervisor role replacement: a role whose thread dies is restarted until
   shutdown is requested, and dead process records plus expired message and
   process history are pruned on their own intervals without an application

docs/security.md

@@ -36,6 +36,14 @@ 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.
+
 ## Serialization
 
 The built-in serializer accepts JSON-compatible data, normalizes keys to