docs: Update all comments and RDocs for normalize_stale_ttl refactoring

Clarifies that Float::INFINITY normalization happens at the Config level,
not in cache implementations, ensuring accurate documentation across the codebase.

Changes:
- Updated PromptCache#initialize RDoc to note normalization happens in Config
- Updated RailsCacheAdapter#initialize RDoc to note normalization happens in Config
- Updated Config#cache_stale_ttl RDoc to document Float::INFINITY support
- Added normalization note to CONFIGURATION.md (cache_stale_ttl section)
- Added normalization note to CACHING.md (Never-Expiring Cache section)
- All documentation now accurately reflects the normalized value flow

Benefits:
- Developers understand where normalization occurs
- Cache class documentation is accurate (receives normalized values)
- Config documentation explains Float::INFINITY handling
- Consistent messaging across code and documentation

Author: drborges

docs/CACHING.md

@@ -198,10 +198,12 @@ Langfuse.configure do |config|
   config.cache_backend = :memory
   config.cache_ttl = 300  # Still refreshes every 5 minutes
   config.cache_stale_while_revalidate = true
-  config.cache_stale_ttl = Float::INFINITY  # Never expire (serve stale forever)
+  config.cache_stale_ttl = Float::INFINITY  # Never expire (normalized to 1000 years internally)
 end
 ```
 
+**Note:** `Float::INFINITY` is automatically normalized to 1000 years (31,557,600,000 seconds) during configuration initialization. This provides a practical "never expire" behavior while keeping the value finite for calculations.
+
 ### Cache States
 
 SWR introduces three cache states instead of two:

docs/CONFIGURATION.md

@@ -147,10 +147,11 @@ See [CACHING.md](CACHING.md#stale-while-revalidate-swr) for detailed usage.
 - **Type:** Integer (seconds) or `Float::INFINITY`
 - **Default:** `0` (SWR disabled)
 - **Description:** Grace period for serving stale data during background refresh
+- **Note:** `Float::INFINITY` is automatically normalized to 1000 years (31,557,600,000 seconds) during config initialization
 
 ```ruby
 config.cache_stale_ttl = 300  # Serve stale data for up to 5 minutes
-config.cache_stale_ttl = Float::INFINITY  # Never expire (1000 years)
+config.cache_stale_ttl = Float::INFINITY  # Never expire (normalized to 1000 years internally)
 ```
 
 **How it works:**

lib/langfuse/config.rb

@@ -50,6 +50,7 @@ class Config
     attr_accessor :cache_stale_while_revalidate
 
     # @return [Integer] Stale TTL in seconds (grace period for serving stale data, default: 0 when SWR disabled, cache_ttl when SWR enabled)
+    #   Accepts Float::INFINITY which is automatically normalized to 1000 years (31,557,600,000 seconds) for practical "never expire" behavior.
     attr_accessor :cache_stale_ttl
 
     # @return [Integer] Number of background threads for cache refresh

lib/langfuse/prompt_cache.rb

@@ -59,7 +59,8 @@ def expired?
     #
     # @param ttl [Integer] Time-to-live in seconds (default: 60)
     # @param max_size [Integer] Maximum cache size (default: 1000)
-    # @param stale_ttl [Integer, Float::INFINITY, nil] Stale TTL for SWR (default: 0, SWR disabled). Use Float::INFINITY for 1000 years, e.g. non-expiring cache.
+    # @param stale_ttl [Integer] Stale TTL for SWR in seconds (default: 0, SWR disabled).
+    #   Note: Float::INFINITY is normalized to 1000 years by Config before being passed here.
     # @param refresh_threads [Integer] Number of background refresh threads (default: 5)
     # @param logger [Logger, nil] Logger instance for error reporting (default: nil, creates new logger)
     def initialize(ttl: 60, max_size: 1000, stale_ttl: 0, refresh_threads: 5, logger: default_logger)

lib/langfuse/rails_cache_adapter.rb

@@ -24,7 +24,8 @@ class RailsCacheAdapter
     # @param ttl [Integer] Time-to-live in seconds (default: 60)
     # @param namespace [String] Cache key namespace (default: "langfuse")
     # @param lock_timeout [Integer] Lock timeout in seconds for stampede protection (default: 10)
-    # @param stale_ttl [Integer, Float::INFINITY, nil] Stale TTL for SWR (default: 0, SWR disabled). Use Float::INFINITY for 1000 years, e.g. non-expiring cache.
+    # @param stale_ttl [Integer] Stale TTL for SWR in seconds (default: 0, SWR disabled).
+    #   Note: Float::INFINITY is normalized to 1000 years by Config before being passed here.
     # @param refresh_threads [Integer] Number of background refresh threads (default: 5)
     # @param logger [Logger, nil] Logger instance for error reporting (default: nil, creates new logger)
     # @raise [ConfigurationError] if Rails.cache is not available