docs: Clarify the monotonic time-in-state documentation

lib/ldclient-rb/impl/data_source/status_provider.rb

@@ -49,14 +49,11 @@ def status
         end
 
         #
-        # The current status together with the seconds the data source has spent
-        # in its current state, read atomically under one lock acquisition so the
-        # duration can never be paired with a stale state.
+        # Returns the current status and the seconds it has been in that state.
         #
-        # The duration is measured on the monotonic clock, so a wall-clock step
-        # cannot distort it. `status.state_since` remains the wall-clock time
-        # reported to applications; this duration is the value to use when it
-        # decides behavior.
+        # One lock acquisition keeps the pair consistent. The seconds are
+        # monotonic — use them for duration decisions instead of arithmetic on
+        # the wall-clock `state_since`.
         #
         # @private
         # @return [Array(LaunchDarkly::Interfaces::DataSource::Status, Float)]

lib/ldclient-rb/impl/data_system/fdv2.rb

@@ -515,6 +515,9 @@ def record_environment_id(environment_id)
         #
         # Determine if we should fallback to the next synchronizer.
         #
+        # The caller supplies the elapsed time because the monotonic baseline is
+        # private to the status provider; see StatusProviderV2#status_and_seconds_in_state.
+        #
         # @param status [LaunchDarkly::Interfaces::DataSource::Status] Current data source status
         # @param seconds_in_state [Float] monotonic seconds spent in status.state
         # @return [Boolean] true if fallback condition is met
@@ -531,6 +534,9 @@ def fallback_condition(status, seconds_in_state)
         #
         # Determine if we should recover to the primary synchronizer.
         #
+        # The caller supplies the elapsed time because the monotonic baseline is
+        # private to the status provider; see StatusProviderV2#status_and_seconds_in_state.
+        #
         # @param status [LaunchDarkly::Interfaces::DataSource::Status] Current data source status
         # @param seconds_in_state [Float] monotonic seconds spent in status.state
         # @return [Boolean] true if recovery condition is met (healthy for too long)