Telemetry Buffer

┌───────────────────────────────────────────────────────────────────────────┐
│                              Client                                       │
│   captureEvent / captureTransaction / captureReplay / captureLogs / ...   │
└───────────────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                          TelemetryBuffer                                  │
│  - Holds per-category buffers                                             │
│  - Early rate-limit check (shared RateLimiter)                            │
│  - Method-based submit to per-category buffers                            │
└───────────────────────────────────────────────────────────────────────────┘
                               │
               ┌───────────────┼────────────────────────────────┐
               ▼               ▼                                ▼
┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
│  Errors/Feedback      │ │  Sessions/CheckIns    │ │  Log                  │
│  (CRITICAL)           │ │  (HIGH)               │ │  (MEDIUM)             │
│  RingBuffer + Batcher │ │  RingBuffer + Batcher │ │  RingBuffer + Batcher │
└───────────────────────┘ └───────────────────────┘ └───────────────────────┘
               │               │                                │
               ▼               ▼                                ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                    EnvelopeScheduler (Weighted RR)                        │
│  - Cross-buffer selection by priority (5..1)                              │
│  - Re-checks RateLimiter before send                                      │
│  - Submits envelopes to transport                                         │
└───────────────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                        Transport (unchanged).                             │
│   - Single worker, disk cache, offline retry, client reports              │
└───────────────────────────────────────────────────────────────────────────┘

enum class EnvelopePriority(val weight: Int) {
  CRITICAL(5), HIGH(4), MEDIUM(3), LOW(2), LOWEST(1)
}

interface TelemetryBuffer<T> {
  val category: DataCategory
  val priority: EnvelopePriority
  fun offer(item: T): OfferResult // may drop; record client report
  fun nextBatchReady(nowMs: Long): Boolean
  fun drainBatch(maxItems: Int, nowMs: Long): List<T>
  fun size(): Int
}

class Client(
  private val buffers: Map<DataCategory, TelemetryBuffer<Any>>,
  private val rateLimiter: RateLimiter,
  private val clientReports: ClientReportRecorder
) {
  fun captureEvent(event: Any) = submit(DataCategory.Error, event)
  fun captureTransaction(tx: Any) = submit(DataCategory.Transaction, tx)
  fun captureReplay(replay: Any) = submit(DataCategory.Replay, replay)
  fun captureLog(log: Any) = submit(DataCategory.Log, log)
  // ... other capture methods ...

  private fun submit(category: DataCategory, item: Any) {
    if (rateLimiter.isRateLimitActive(category)) {
      clientReports.recordLostEvent(DiscardReason.RATELIMIT_BACKOFF, category)
      return
    }
    val res = buffers[category]?.offer(item)
    if (res is OfferResult.Dropped) {
      clientReports.recordLostEvent(DiscardReason.QUEUE_OVERFLOW, category, res.count)
    }
  }
}

class EnvelopeScheduler(
  private val buffersByPriority: Map<EnvelopePriority, List<TelemetryBuffer<*>>,
  private val transport: ITransport,
  private val rateLimiter: RateLimiter,
  private val clientReports: ClientReportRecorder,
  private val weights: Map<EnvelopePriority, Int>,
  private val backoffMs: Long
) : Thread("TelemetryEnvelopeScheduler") {
  override fun run() {
    val order = generatePriorityCycle(weights) // e.g., [CRITICAL×5, HIGH×4, ...]
    while (true) {
      var sentSomething = false
      for (p in order) {
        val buf = selectReadyBuffer(buffersByPriority[p])
        if (buf != null) {
          val cat = buf.category
          val batch = buf.drainBatch(maxItemsFor(cat), nowMs())
          if (batch.isNotEmpty()) {
            if (!rateLimiter.isRateLimitActive(cat)) {
              val envelopes = buildEnvelopes(cat, batch)
              for (env in envelopes) {
                transport.send(env)
              }
              sentSomething = true
            } else {
              clientReports.recordLostEvent(DiscardReason.RATELIMIT_BACKOFF, cat, batch.size)
            }
          }
        }
      }
      if (!sentSomething) sleep(backoffMs)
    }
  }

  private fun buildEnvelopes(category: DataCategory, batch: List<Any>): List<Envelope> {
    // Applies SDK version, trace context if provided, and size constraints
    // Returns one or more envelopes constructed from the batch
    TODO()
  }
}