refactor: prompt cache internals

docs/API_REFERENCE.md

@@ -52,8 +52,8 @@ Block receives a `Langfuse::Config` object with these properties:
 | `flush_interval`               | Integer | No       | `10`                           | Score + trace export interval (s) |
 | `sample_rate`                  | Float   | No       | `1.0`                          | Trace + trace-linked score sampling rate (`0.0..1.0`) |
 | `logger`                       | Logger  | No       | Auto-detected                  | Logger instance                   |
-| `tracing_async`                | Boolean | No       | `true`                         | ⚠️ Experimental (OTel export mode) |
-| `job_queue`                    | Symbol  | No       | `:default`                     | ⚠️ Experimental (not implemented) |
+| `tracing_async`                | Boolean | No       | `true`                         | ⚠️ Experimental (OTel batch scheduling) |
+| `job_queue`                    | Symbol  | No       | `:default`                     | Reserved/no-op for future job integration |
 | `environment`                  | String  | No       | `nil` (or `ENV["LANGFUSE_TRACING_ENVIRONMENT"]`) | Default trace environment          |
 | `release`                      | String  | No       | `nil` (or `ENV["LANGFUSE_RELEASE"]` / common CI commit SHA env) | Default release identifier         |
 | `should_export_span`           | `#call` | No       | `nil`                          | Span export filter callback        |

docs/CONFIGURATION.md

@@ -301,8 +301,8 @@ config.logger = Logger.new(IO::NULL)
 
 - **Type:** Boolean
 - **Default:** `true`
-- **Status:** Implemented for OpenTelemetry batching; ActiveJob integration is not implemented
-- **Description:** Controls OpenTelemetry export behavior. When `true`, spans are exported in the background on a schedule. When `false`, spans are still batched with a longer schedule delay and are typically flushed explicitly at lifecycle boundaries.
+- **Status:** Implemented for OpenTelemetry batch scheduling; ActiveJob integration is not implemented
+- **Description:** Controls OpenTelemetry export scheduling. When `true`, spans use the configured `flush_interval` schedule. When `false`, spans still use OpenTelemetry's batch processor with a long schedule delay and are typically flushed explicitly at lifecycle boundaries.
 
 ```ruby
 config.tracing_async = true
@@ -314,11 +314,11 @@ config.tracing_async = true
 
 - **Type:** Symbol
 - **Default:** `:default`
-- **Status:** Not yet implemented (placeholder)
-- **Description:** Future: ActiveJob queue name for async tracing
+- **Status:** Reserved/no-op
+- **Description:** Reserved for a future ActiveJob integration. It is kept for configuration compatibility and has no runtime effect today.
 
 ```ruby
-config.job_queue = :langfuse  # Placeholder - no effect currently
+config.job_queue = :langfuse  # Reserved/no-op today
 ```
 
 **Current Behavior:** No ActiveJob integration yet. Reserved for future implementation.

lib/langfuse.rb

@@ -44,6 +44,7 @@ class UnauthorizedError < ApiError; end
 require_relative "langfuse/prompt_cache"
 require_relative "langfuse/prompt_fetch_result"
 require_relative "langfuse/rails_cache_adapter"
+require_relative "langfuse/prompt_cache_coordinator"
 require_relative "langfuse/cache_warmer"
 require_relative "langfuse/prompt_cache_events"
 require_relative "langfuse/api_client"