fix: Align payload and timeout behavior

Guard and isolate payload projections, honor configured byte limits,
and preserve generated defaults within each committed snapshot.
Normalize timeout telemetry to the shared JavaScript contract.

Let SQLite lock holders run during background busy waits on older
Rails versions, reinstalling the yielding handler on each attempt.
Cover the behavior with shared fixtures, real adapter regressions,
and reversal checks.

Author: cardmagic

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+- Guard personalized payload projections against state changes, staged work,
+  and application database writes. Each payload gets an isolated actor from
+  the committed snapshot and honors `max_payload_bytes`, matching JavaScript.
+- Preserve timeout wait reasons, activation owner IDs, and activation generations
+  in portable telemetry using the shared camelCase fields and reason values.
+- Use a yielding SQLite busy handler for background transactions so concurrent
+  writers can finish on Rails 7.1 and 7.2. Preserve configured wait limits and
+  synchronous deadlines; cover contention with a coordinated lock regression.
+
 - Reject query and observable state mutation and staged durable work with
   terminal `QueryMutatedState` errors. Cover individual snapshot projections and
   preserve ordinary operations' already-staged work while reading projections,

compatibility/sync-timeout.json

@@ -0,0 +1,10 @@
+[
+  { "rubyReason": "actor_paused", "waitingOn": "actorPaused" },
+  { "rubyReason": "activation_held", "waitingOn": "activationHeld" },
+  { "rubyReason": "earlier_message", "waitingOn": "earlierMessage" },
+  { "rubyReason": "message_claimed", "waitingOn": "messageClaimed" },
+  { "rubyReason": "not_yet_available", "waitingOn": "notYetAvailable" },
+  { "rubyReason": "ready_unclaimed", "waitingOn": "readyUnclaimed" },
+  { "rubyReason": "database_contention", "waitingOn": "databaseContention" },
+  { "rubyReason": "unknown", "waitingOn": "unknown" }
+]

docs/observability.md

@@ -47,6 +47,17 @@ Portable `polling.interval_changed` events carry `previousIntervalMilliseconds`,
 `currentIntervalMilliseconds`, and a string `reason`. Ruby converts its native
 second-based notification values while preserving the original notification.
 
+## Synchronous timeout diagnostics
+
+`solid_objects.sync.timeout` includes `waitingOn`, `activationOwnerId`, and
+`activationGeneration` in `attributes`. Generations are decimal strings;
+unavailable activation fields are null. Both runtimes use the same wait reasons:
+`actorPaused`, `activationHeld`, `earlierMessage`, `messageClaimed`,
+`notYetAvailable`, `readyUnclaimed`, `databaseContention`, and `unknown`.
+Ruby's exception attributes and Active Support notifications retain their native
+snake_case names and reason values. The portable instrumentation envelope uses
+the shared camelCase contract.
+
 ## Metrics and tracing
 
 Metrics are sample descriptions. Exporting them is opt-in: the runtime does not

docs/roadmap.md

@@ -3,13 +3,16 @@
 ## Implemented and tested
 
 - Portable telemetry with a shared JSON schema, metric samples, isolated observer
-  callbacks, and bounded authorized actor diagnostics. See [observability](observability.md).
+  callbacks, bounded authorized actor diagnostics, and matching timeout wait
+  reasons and activation metadata. See [observability](observability.md).
 
 - Rails engine, install generator, migration, and CLI
 - Explicit actor registry, references, JSON state, and state migrations
-- Queries and observable projections reject state mutation and staged durable
-  work with terminal `QueryMutatedState` errors, matching JavaScript. Shared JSON
-  fixtures preserve reserved property names as ordinary data in both runtimes.
+- Queries, observable projections, and personalized payloads reject state mutation
+  and staged durable work with `QueryMutatedState`, matching JavaScript. Query
+  and observable violations fail terminally; a payload violation is confined to
+  that payload. Shared JSON fixtures preserve reserved property names as ordinary
+  data in both runtimes.
 - Fluent direct synchronous RPC, configured `sync`, and durable `async`
 - Durable message history plus ready/claimed membership tables
 - Concurrent sequence allocation and actor creation. An enqueue finds the
@@ -61,7 +64,9 @@
   subscriber's authorization context, fenced by actor revision, resolved through
   `payload_authorization_context` so the block and `authorize_query` see the
   same subject a controller render passes, and confined so one failing payload
-  cannot reject the subscription or stop its siblings
+  cannot reject the subscription or stop its siblings. Each payload uses an
+  isolated actor from the same committed snapshot, prevents application database
+  writes, and enforces the configured `max_payload_bytes` limit
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
   migration cookbook. The doctor names every column that a migration after the

lib/solid_objects/actor.rb

@@ -545,26 +545,26 @@ def intent_count
         reminder_intents.length + outbound_message_intents.length
     end
 
-    private
-
-    attr_reader :effect_intents,
-      :effect_recovery_intents,
-      :commit_action_intents,
-      :reminder_intents,
-      :outbound_message_intents
-
     # @rbs (String) { () -> untyped } -> untyped
     def read_projection(operation)
       state_before = state.to_h
       intents_before = intent_snapshot
       result = guard_application_writes(operation) { yield }
       unless state.to_h == state_before && intent_snapshot == intents_before
-        raise QueryMutatedState, "observables must not mutate actor state or stage durable work"
+        raise QueryMutatedState, "projections must not mutate actor state or stage durable work"
       end
 
       result
     end
 
+    private
+
+    attr_reader :effect_intents,
+      :effect_recovery_intents,
+      :commit_action_intents,
+      :reminder_intents,
+      :outbound_message_intents
+
     # @rbs () -> Array[Array[Hash[Symbol, untyped]]]
     def intent_snapshot
       [ effect_intents, effect_recovery_intents, commit_action_intents, reminder_intents, outbound_message_intents ].map do |intents|

lib/solid_objects/actor_snapshot.rb

@@ -7,6 +7,7 @@ class ActorSnapshot
     # @rbs @actor: Actor
     # @rbs @instance_id: Integer
     # @rbs @revision: Integer
+    # @rbs @state_data: Hash[String, untyped]
     # @rbs @observable_values: Hash[String, untyped]?
     # @rbs @observable_value_cache: Hash[String, untyped]
 
@@ -24,6 +25,7 @@ def initialize(reference)
       end
       @instance_id = @instance&.id || 0
       @revision = @instance&.state_revision || 0
+      @state_data = State.new(actor_class.definition.state_definition, migrated_state).to_h
       @actor = build_actor
       @observable_values = nil
       @observable_value_cache = {}
@@ -43,14 +45,23 @@ def observable_value(name)
         Serialization.readonly_copy(actor.observable_value(observable_name))
     end
 
+    # @rbs () -> Actor
+    def build_actor
+      actor_class.new(
+        actor_id: reference.actor_id,
+        state: State.new(actor_class.definition.state_definition, @state_data),
+        instance_id: instance&.id
+      )
+    end
+
     private
 
     attr_reader :instance
 
-    # @rbs () -> Actor
-    def build_actor
+    # @rbs () -> Hash[String, untyped]
+    def migrated_state
       state_version = instance&.state_version || actor_class.state_version
-      state_data = ApplicationWriteGuard.call(
+      ApplicationWriteGuard.call(
         actor_type: reference.actor_type,
         actor_id: reference.actor_id,
         operation: "state_migration"
@@ -60,11 +71,6 @@ def build_actor
           instance&.state || {}
         )
       end
-      actor_class.new(
-        actor_id: reference.actor_id,
-        state: State.new(actor_class.definition.state_definition, state_data),
-        instance_id: @instance&.id
-      )
     end
   end
 end

lib/solid_objects/database_adapters/sqlite.rb

@@ -22,7 +22,13 @@ def current_time_expression
       def transaction(&block)
         return with_lock_retry { super } if SyncDeadline.active?
 
-        with_busy_retry { super }
+        with_busy_retry do
+          with_connection do |connection|
+            timeout = configured_busy_handler_timeout(connection)
+            connection.raw_connection.busy_handler_timeout = timeout if timeout
+            super
+          end
+        end
       end
 
       # A write outside a synchronous deadline has no Ruby-level budget, so it

lib/solid_objects/payload_broadcast.rb

@@ -2,7 +2,6 @@
 
 module SolidObjects
   class PayloadBroadcast
-    MAXIMUM_PAYLOAD_BYTES = 1_048_576
     REVISION_OBSERVABLE = "solid_objects.revision"
 
     # @rbs @snapshot: ActorSnapshot
@@ -42,7 +41,7 @@ def call
     def rendered_payload(handler)
       payload = Serialization.dump(
         evaluated_payload(handler),
-        max_bytes: MAXIMUM_PAYLOAD_BYTES
+        max_bytes: SolidObjects.configuration.max_payload_bytes
       )
       return payload if payload.is_a?(Hash) || payload.is_a?(Array)
 
@@ -56,10 +55,12 @@ def rendered_payload(handler)
     # unaffected.
     # @rbs (ActorDefinition::Handler) -> untyped
     def evaluated_payload(handler)
-      actor = snapshot.actor
-      actor.instance_exec(actor, authorization_context, &handler.block)
+      actor = snapshot.build_actor
+      actor.read_projection("payload.#{name}") do
+        actor.instance_exec(actor, authorization_context, &handler.block)
+      end
     rescue NameError => error
-      raise unless class_level_receiver?(error)
+      raise unless class_level_receiver?(error, actor)
 
       raise InvalidPayloadBroadcast,
         "payload broadcast #{name.inspect} called #{error.name.inspect} on the " \
@@ -70,9 +71,9 @@ def evaluated_payload(handler)
     # Distinguishes a block that relied on the old class-level receiver from an
     # ordinary typo, so the one behaviour change reports itself instead of
     # surfacing as an unexplained NameError.
-    # @rbs (NameError[untyped]) -> bool
-    def class_level_receiver?(error)
-      error.receiver.equal?(snapshot.actor) &&
+    # @rbs (NameError[untyped], Actor?) -> bool
+    def class_level_receiver?(error, actor)
+      error.receiver.equal?(actor) &&
         snapshot.actor_class.respond_to?(error.name)
     rescue ArgumentError, NameError
       false

lib/solid_objects/telemetry.rb

@@ -9,6 +9,7 @@ module Telemetry
       outboxKind truncated broadcastId code role reason processId processKind ownerId componentCount byteCount
       thresholdBytes previousRunAt nextRunAt name commitAction payload
       previousIntervalMilliseconds currentIntervalMilliseconds
+      waitingOn activationOwnerId activationGeneration
     ].freeze
     ALIASES = { "errorClass" => "errorName", "stateRevision" => "revision", "durationMs" => "durationMilliseconds" }.freeze
 
@@ -89,7 +90,8 @@ def safe_attributes(payload)
           next unless FIELDS.include?(name)
           next unless value.nil? || value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false
 
-          value = value.to_s if !value.nil? && (name.end_with?("Id") || %w[revision sequence generation].include?(name))
+          value = value.camelize(:lower) if name == "waitingOn" && value.is_a?(String)
+          value = value.to_s if !value.nil? && (name.end_with?("Id") || %w[revision sequence generation activationGeneration].include?(name))
           attributes[name] = value
         end
       end

sig/generated/lib/solid_objects/actor.rbs

@@ -351,6 +351,9 @@ module SolidObjects
     # @rbs () -> Integer
     def intent_count: () -> Integer
 
+    # @rbs (String) { () -> untyped } -> untyped
+    def read_projection: (String) { () -> untyped } -> untyped
+
     private
 
     attr_reader effect_intents: untyped
@@ -363,9 +366,6 @@ module SolidObjects
 
     attr_reader outbound_message_intents: untyped
 
-    # @rbs (String) { () -> untyped } -> untyped
-    def read_projection: (String) { () -> untyped } -> untyped
-
     # @rbs () -> Array[Array[Hash[Symbol, untyped]]]
     def intent_snapshot: () -> Array[Array[Hash[Symbol, untyped]]]