expo-observe 58.0.0 → 58.0.3

package/.npmignore

@@ -20,3 +20,8 @@ __rsc_tests__
 # Ensure native dirs aren't excluded by root .gitignore
 !/ios
 !/android
+
+# Exclude native build output (pnpm pack ignores nested .gitignore files)
+.cxx/
+.gradle/
+/android/build/

package/CHANGELOG.md

@@ -10,6 +10,18 @@
 
 ### 💡 Others
 
+## 58.0.3 — 2026-09-14
+
+_This version does not introduce any user-facing changes._
+
+## 58.0.2 — 2026-09-14
+
+_This version does not introduce any user-facing changes._
+
+## 58.0.1 — 2026-09-14
+
+_This version does not introduce any user-facing changes._
+
 ## 58.0.0 — 2026-09-10
 
 ### 🎉 New features
@@ -19,10 +31,12 @@
 - Add `reportError` to report caught, non-fatal errors from your own `try`/`catch` blocks. ([#47871](https://github.com/expo/expo/pull/47871) by [@tsapeta](https://github.com/tsapeta))
 - Add an `errorHandlingEnabled` option to `configure` to opt out of recording unhandled JavaScript errors. ([#48506](https://github.com/expo/expo/pull/48506) by [@tsapeta](https://github.com/tsapeta))
 - Add `Observe.clientId`, the EAS client id recorded on every event, so apps can correlate Observe data with other services. ([#49599](https://github.com/expo/expo/pull/49599) by [@kadikraman](https://github.com/kadikraman))
+- Export network requests as OTLP traces. ([#48883](https://github.com/expo/expo/pull/48883) by [@tsapeta](https://github.com/tsapeta))
 
 ### 🐛 Bug fixes
 
 - Fix OTel date conversion ([#48161](https://github.com/expo/expo/pull/48161) by [@Ubax](https://github.com/Ubax))
+- [iOS] Stop overlapping dispatches from sending the same pending rows twice. `dispatchEvents()` now waits for a dispatch already in progress instead of overlapping with it. ([#48883](https://github.com/expo/expo/pull/48883) by [@tsapeta](https://github.com/tsapeta))
 - [Android] Explicitly enable `buildFeatures.buildConfig`, required by AGP 9. ([#47729](https://github.com/expo/expo/pull/47729) by [@gabrieldonadel](https://github.com/gabrieldonadel))
 
 ### 💡 Others

package/android/src/main/java/expo/modules/observe/Event.kt

@@ -145,3 +145,13 @@ data class Event(
   val metrics: List<EASMetric>,
   val logs: List<LogEvent> = emptyList()
 )
+
+/**
+ * One session's spans paired with the event carrying that session's resource metadata, ready
+ * for the traces dispatch. Spans travel separately from `Event` because they aren't part of
+ * the payload shape the metrics/logs signals share.
+ */
+data class SpanBatch(
+  val event: Event,
+  val spans: List<OTSpan>
+)

package/android/src/main/java/expo/modules/observe/EventDispatcher.kt

@@ -27,6 +27,8 @@ class EventDispatcher(
 
   private fun logsEndpointUrl(): String = "$baseProjectUrl/v1/logs"
 
+  private fun tracesEndpointUrl(): String = "$baseProjectUrl/v1/traces"
+
   /**
    * POSTs `events` to the metrics endpoint and classifies the response per the OTLP retry
    * spec. Non-throwing: payload-encoding errors collapse to `NonRetryable` (same bytes will
@@ -76,6 +78,30 @@ class EventDispatcher(
       executePost(continuation, logsEndpointUrl(), body)
     }
 
+  /**
+   * Dispatches span batches to `{baseUrl}/{projectId}/v1/traces`. Each batch carries one
+   * session's spans plus the event holding that session's resource metadata.
+   */
+  suspend fun dispatchSpans(batches: List<SpanBatch>): DispatchResult =
+    suspendCancellableCoroutine { continuation ->
+      if (batches.isEmpty()) {
+        // Empty input isn't a server response - signal success.
+        continuation.resume(DispatchResult.Success)
+        return@suspendCancellableCoroutine Unit
+      }
+      val easId = EASClientID(context).uuid.toString()
+      val body = try {
+        OTTracesRequestBody(
+          resourceSpans = batches.map { it.event.toOTResourceSpans(easId, it.spans) }
+        ).toJson(prettyPrint = true)
+      } catch (e: Exception) {
+        Log.w(OBSERVE_TAG, "Encoding traces request body failed: ${e.message}")
+        continuation.resume(DispatchResult.NonRetryableFailure("encoding error: ${e.message}"))
+        return@suspendCancellableCoroutine Unit
+      }
+      executePost(continuation, tracesEndpointUrl(), body)
+    }
+
   private fun executePost(
     continuation: kotlinx.coroutines.CancellableContinuation<DispatchResult>,
     endpointUrl: String,

package/android/src/main/java/expo/modules/observe/ObservabilityBackgroundWorker.kt

@@ -18,7 +18,7 @@ import androidx.work.workDataOf
 import expo.modules.appmetrics.storage.SessionManager
 
 /**
- * Background worker that dispatches stored metrics and logs to EAS Observe.
+ * Background worker that dispatches stored metrics, logs, and spans to EAS Observe.
  */
 class ObservabilityBackgroundWorker(
   context: Context,
@@ -72,10 +72,11 @@ class ObservabilityBackgroundWorker(
       observabilityManager.cleanup()
       observabilityManager.dispatchUnsentMetrics()
       observabilityManager.dispatchUnsentLogs()
-      Log.d(OBSERVE_TAG, "Successfully dispatched unsent metrics and logs")
+      observabilityManager.dispatchUnsentSpans()
+      Log.d(OBSERVE_TAG, "Successfully dispatched unsent metrics, logs, and spans")
       Result.success()
     } catch (e: Exception) {
-      Log.e(OBSERVE_TAG, "Failed to dispatch metrics", e)
+      Log.e(OBSERVE_TAG, "Failed to dispatch metrics, logs, and spans", e)
       // Retry with exponential backoff
       Result.retry()
     }
@@ -108,7 +109,7 @@ class ObservabilityBackgroundWorker(
         .getInstance(context)
         .enqueueUniqueWork(
           WORK_NAME,
-          // Keep an in-flight dispatch; cancelling it can duplicate a request the server received.
+          // Keep an in-flight dispatch; canceling it can duplicate a request the server received.
           ExistingWorkPolicy.KEEP,
           periodicWork
         )

package/android/src/main/java/expo/modules/observe/ObservabilityManager.kt

@@ -4,6 +4,7 @@ import android.content.Context
 import android.util.Log
 import expo.modules.easclient.EASClientID
 import expo.modules.appmetrics.storage.SessionManager
+import expo.modules.appmetrics.storage.Span
 import expo.modules.appmetrics.utils.TimeUtils
 import expo.modules.interfaces.constants.ConstantsInterface
 import kotlinx.coroutines.currentCoroutineContext
@@ -49,6 +50,10 @@ class ObservabilityManager(
     baseManager.dispatchUnsentLogs()
   }
 
+  suspend fun dispatchUnsentSpans() {
+    baseManager.dispatchUnsentSpans()
+  }
+
   fun scheduleBackgroundDispatch() {
     ObservabilityBackgroundWorker.scheduleBackgroundDispatch(
       context = context,
@@ -91,6 +96,7 @@ class BaseObservabilityManager(
    */
   private var metricsRetryGate: DispatchUtils.RetryGateState = DispatchUtils.RetryGateState.initial
   private var logsRetryGate: DispatchUtils.RetryGateState = DispatchUtils.RetryGateState.initial
+  private var spansRetryGate: DispatchUtils.RetryGateState = DispatchUtils.RetryGateState.initial
 
   /**
    * Returns true and logs when an active retry gate suppresses this dispatch round. Called
@@ -276,6 +282,90 @@ class BaseObservabilityManager(
     }
   }
 
+  /**
+   * Dispatches persisted spans to `/v1/traces`.
+   *
+   * Unlike metrics and logs there is no persisted cursor yet: a consumed (or deliberately
+   * dropped) batch is deleted outright and the table itself acts as the queue. Rows survive
+   * on a retryable failure and go out on the next dispatch. Batches are chunked at the
+   * server's per-request span limit.
+   */
+  suspend fun dispatchUnsentSpans(): Unit = spansDispatchMutex.withLock {
+    if (retryGateBlocks(spansRetryGate, "spans")) {
+      return
+    }
+
+    if (!shouldDispatch()) {
+      // Mirrors metrics/logs advancing the cursor past rows they won't send.
+      sessionManager.getMaxSpanId()?.let { sessionManager.deleteSpansUpTo(it) }
+      return
+    }
+
+    // Rows are read in id order one server-sized chunk at a time; a chunk that fails retryably
+    // stops the loop and leaves its rows (and everything after them) for the next dispatch. An
+    // oversized chunk is split in half and retried, so one huge span doesn't drop its whole
+    // chunk.
+    var readCursor = -1L
+    val chunks = ArrayDeque<List<Span>>()
+    while (currentCoroutineContext().isActive) {
+      if (chunks.isEmpty()) {
+        val nextChunk = sessionManager.getSpans(readCursor, MAX_SPANS_PER_REQUEST)
+        if (nextChunk.isEmpty()) {
+          return
+        }
+        readCursor = nextChunk.last().id
+        chunks.addLast(nextChunk)
+      }
+      val chunk = chunks.removeFirst()
+      val spansBySessionId = chunk.groupBy { it.sessionId }
+      // Batched because an offline backlog spans many sessions, and each halving retry would
+      // otherwise re-run every lookup.
+      val sessions = sessionManager.getSessions(spansBySessionId.keys).associateBy { it.id }
+      val batches = spansBySessionId.mapNotNull { (sessionId, spans) ->
+        // Spans whose session row no longer exists are skipped, because their rows are about to be
+        // deleted below anyway.
+        val session = sessions[sessionId] ?: return@mapNotNull null
+        SpanBatch(
+          event = Event(metadata = Metadata.fromSessionMetadata(session), metrics = emptyList()),
+          spans = spans.map { it.toOTSpan() }
+        )
+      }
+      val highestId = chunk.last().id
+      if (batches.isEmpty()) {
+        sessionManager.deleteSpansUpTo(highestId)
+        continue
+      }
+      val result = eventDispatcher.dispatchSpans(batches)
+      spansRetryGate = nextGate(spansRetryGate, result)
+      when (result) {
+        is DispatchResult.PartialSuccess ->
+          Log.w(
+            OBSERVE_TAG,
+            "Partial success on batch of ${chunk.size} span(s): " +
+              "server rejected ${result.partial.rejectedCount} " +
+              "(${result.partial.errorMessage ?: "no error message"})"
+          )
+        is DispatchResult.NonRetryableFailure ->
+          Log.w(OBSERVE_TAG, "Dropping batch of ${chunk.size} span(s): ${result.reason}")
+        DispatchResult.PayloadTooLarge -> if (chunk.size == 1) {
+          Log.w(OBSERVE_TAG, "Dropping span that exceeds the server's payload limit")
+        }
+        DispatchResult.Success, is DispatchResult.RetryableFailure -> Unit
+      }
+      when (spanDispatchDisposition(result, chunk.size)) {
+        SpanDispatchDisposition.HALVE_AND_RETRY -> {
+          // `toList()` rather than the `subList` views: nested views would keep the whole
+          // original chunk (up to 512 rows with their JSON blobs) reachable until every
+          // descendant had been processed. Matches iOS, which materializes with `Array`.
+          chunks.addFirst(chunk.subList(chunk.size / 2, chunk.size).toList())
+          chunks.addFirst(chunk.subList(0, chunk.size / 2).toList())
+        }
+        SpanDispatchDisposition.DELETE_AND_CONTINUE -> sessionManager.deleteSpansUpTo(highestId)
+        SpanDispatchDisposition.KEEP_AND_STOP -> return
+      }
+    }
+  }
+
   private fun isInSample(): Boolean {
     val rate = ObservePreferences.getConfig(context)?.sampleRate ?: return true
     val clamped = rate.coerceIn(0.0, 1.0)
@@ -303,8 +393,15 @@ class BaseObservabilityManager(
   }
 
   companion object {
+    /**
+     * Maximum spans per request accepted by the ingestion endpoint; it rejects everything past
+     * this count within one POST, so larger backlogs are sent as sequential chunks.
+     */
+    const val MAX_SPANS_PER_REQUEST = 512
+
     // Serialize foreground and background dispatches without blocking the other signal.
     private val metricsDispatchMutex = Mutex()
     private val logsDispatchMutex = Mutex()
+    private val spansDispatchMutex = Mutex()
   }
 }

package/android/src/main/java/expo/modules/observe/ObserveModule.kt

@@ -66,6 +66,7 @@ class ObserveModule : Module() {
       AsyncFunction("dispatchEvents") Coroutine { ->
         observabilityManager.dispatchUnsentMetrics()
         observabilityManager.dispatchUnsentLogs()
+        observabilityManager.dispatchUnsentSpans()
       }
 
       Function("configure") { config: Config ->

package/android/src/main/java/expo/modules/observe/OpenTelemetry.kt

@@ -6,6 +6,7 @@ import expo.modules.appmetrics.logevents.Severity
 import expo.modules.appmetrics.utils.TimeUtils.timestampToDateNS
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
 import kotlinx.serialization.json.JsonElement
 import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.JsonPrimitive
@@ -134,6 +135,59 @@ data class OTResourceLogs(
   val schemaUrl: String
 )
 
+/**
+ * One OTLP span, per https://opentelemetry.io/docs/concepts/signals/traces/#spans.
+ *
+ * Nullable fields with defaults (`parentSpanId`, `status`) rely on kotlinx-serialization omitting
+ * defaults: the ingestion endpoint rejects a span whose present `parentSpanId` isn't valid hex, so
+ * a root span must omit the key entirely rather than send null or "".
+ */
+@Serializable
+data class OTSpan(
+  val traceId: String,
+  val spanId: String,
+  val parentSpanId: String? = null,
+  val name: String,
+  val kind: Int,
+  val startTimeUnixNano: Long,
+  val endTimeUnixNano: Long,
+  val attributes: List<OTAttribute>,
+  val events: List<OTSpanEvent>,
+  val droppedEventsCount: Int = 0,
+  val status: OTSpanStatus? = null
+)
+
+/** `Span.Event` per the OTLP proto, used for redirect hops. */
+@Serializable
+data class OTSpanEvent(
+  val timeUnixNano: Long,
+  val name: String,
+  val attributes: List<OTAttribute>
+)
+
+/**
+ * `Status` per the OTLP proto. Only attached when the span represents a failure; a successful
+ * client span stays UNSET by omitting the status entirely, per the semantic conventions.
+ */
+@Serializable
+data class OTSpanStatus(
+  val code: Int,
+  val message: String? = null
+)
+
+@Serializable
+data class OTScopeSpans(
+  val scope: OTScope,
+  val spans: List<OTSpan>
+)
+
+@Serializable
+data class OTResourceSpans(
+  val resource: OTMetadata,
+  val scopeSpans: List<OTScopeSpans>,
+  val schemaUrl: String
+)
+
 // MARK: -- Request body for Open Telemetry events
 
 @Serializable
@@ -160,6 +214,18 @@ data class OTLogsRequestBody(
   }
 }
 
+@Serializable
+data class OTTracesRequestBody(
+  val resourceSpans: List<OTResourceSpans>
+) {
+  fun toJson(prettyPrint: Boolean = false): String {
+    val json = Json {
+      this.prettyPrint = prettyPrint
+    }
+    return json.encodeToString(serializer(), this)
+  }
+}
+
 // MARK: -- Response shapes
 
 /**
@@ -177,10 +243,11 @@ data class OTLogsRequestBody(
 data class OTPartialSuccess(
   val rejectedDataPoints: Int? = null,
   val rejectedLogRecords: Int? = null,
+  val rejectedSpans: Int? = null,
   val errorMessage: String? = null
 ) {
   val rejectedCount: Int
-    get() = (rejectedDataPoints ?: 0) + (rejectedLogRecords ?: 0)
+    get() = (rejectedDataPoints ?: 0) + (rejectedLogRecords ?: 0) + (rejectedSpans ?: 0)
 }
 
 @Serializable
@@ -399,6 +466,99 @@ fun Event.toOTResourceLogs(easClientId: String): OTResourceLogs {
   )
 }
 
+/**
+ * Wraps already-mapped spans in this event's resource envelope. Spans are passed in rather than
+ * derived from the event because they come from `spans` rows, which are not part of the `Event`
+ * payload shape the metrics/logs signals share.
+ */
+fun Event.toOTResourceSpans(easClientId: String, spans: List<OTSpan>): OTResourceSpans {
+  return OTResourceSpans(
+    resource = toOTMetadata(easClientId),
+    scopeSpans = listOf(
+      OTScopeSpans(
+        scope = OTScope(name = "expo-observe", version = BuildConfig.EXPO_OBSERVE_VERSION),
+        spans = spans
+      )
+    ),
+    schemaUrl = SEMCONV_SCHEMA_URL
+  )
+}
+
+/**
+ * Maximum span events the ingestion endpoint keeps per span; anything past it is counted as
+ * dropped server-side, so the SDK truncates locally and reports the loss itself instead of
+ * shipping payload that is guaranteed to be discarded.
+ */
+private const val MAX_SPAN_EVENT_COUNT = 32
+
+/**
+ * Converts a persisted unix-epoch millisecond timestamp to nanoseconds, saturating instead of
+ * overflowing: a corrupt row or a device clock set far into the future must never wrap into a
+ * negative timestamp.
+ */
+private fun spanNanosecondsFromMilliseconds(milliseconds: Long): Long {
+  val maxRepresentableMs = Long.MAX_VALUE / 1_000_000
+  return milliseconds.coerceIn(0, maxRepresentableMs) * 1_000_000
+}
+
+/**
+ * Maps one persisted span row onto the OTLP wire shape. The mapping is producer-agnostic:
+ * attributes and events were shaped by whichever producer recorded the row (per its own
+ * semantic conventions), and this conversion only handles the generic concerns: timestamps,
+ * the session attribute, the event cap, and the JSON-to-`AnyValue` typing. Mirrors the iOS
+ * `SpanRow.toOTSpan`.
+ */
+fun expo.modules.appmetrics.storage.Span.toOTSpan(): OTSpan {
+  // Millisecond precision matches the backend's DateTime64(3) storage. A clock adjustment
+  // mid-span can invert the two wall-clock timestamps, and the server rejects a span whose end
+  // precedes its start, so the end clamps to the start.
+  val startNs = spanNanosecondsFromMilliseconds(startTimestampMs)
+  val endNs = maxOf(startNs, spanNanosecondsFromMilliseconds(endTimestampMs))
+
+  val otAttributes = mutableListOf(
+    OTAttribute.of(key = "session.id", rawValue = sessionId)
+  )
+  attributes
+    ?.let { json -> runCatching { Json.decodeFromString<JsonObject>(json) }.getOrNull() }
+    ?.let { obj -> otAttributes.addAll(otAttributesFromJsonObject(obj).first) }
+
+  // The ingestion endpoint keeps at most `MAX_SPAN_EVENT_COUNT` events per span and counts the
+  // rest as dropped; truncating locally reports the same loss without shipping payload that is
+  // guaranteed to be discarded.
+  val allEvents = events
+    ?.let { json -> runCatching { Json.decodeFromString<JsonArray>(json) }.getOrNull() }
+    ?: JsonArray(emptyList())
+  val otEvents = allEvents.take(MAX_SPAN_EVENT_COUNT).mapNotNull { element ->
+    val obj = element as? JsonObject ?: return@mapNotNull null
+    // The server drops nameless events anyway; skipping them locally keeps the payload honest.
+    val name = (obj["name"] as? JsonPrimitive)?.takeIf { it.isString }?.content
+      ?: return@mapNotNull null
+    val eventAttributes = (obj["attributes"] as? JsonObject)
+      ?.let { otAttributesFromJsonObject(it).first }
+      ?: emptyList()
+    // Producers may record a per-event timestamp; without one the event anchors to the span
+    // start, which keeps it inside the span window.
+    val timeNs = (obj["timeMs"] as? JsonPrimitive)?.longOrNull
+      ?.let { spanNanosecondsFromMilliseconds(it) }
+      ?: startNs
+    OTSpanEvent(timeUnixNano = timeNs, name = name, attributes = eventAttributes)
+  }
+
+  return OTSpan(
+    traceId = traceId,
+    spanId = spanId,
+    parentSpanId = parentSpanId,
+    name = name,
+    kind = kind,
+    startTimeUnixNano = startNs,
+    endTimeUnixNano = endNs,
+    attributes = otAttributes,
+    events = otEvents,
+    droppedEventsCount = maxOf(0, allEvents.size - MAX_SPAN_EVENT_COUNT),
+    status = statusCode?.let { OTSpanStatus(code = it, message = statusMessage) }
+  )
+}
+
 internal fun otAnyValueFromJsonElement(element: JsonElement): OTAnyValue? {
   if (element is kotlinx.serialization.json.JsonNull) {
     return null

package/android/src/main/java/expo/modules/observe/SpanDispatchOutcome.kt

@@ -0,0 +1,43 @@
+// Copyright 2025-present 650 Industries. All rights reserved.
+
+package expo.modules.observe
+
+/**
+ * What the span dispatch loop does with a chunk once the server has answered. Mirrors the iOS
+ * `SpanDispatchLoop.Disposition`.
+ *
+ * Spans deliberately do not reuse the metrics and logs loop: that one owns a persisted cursor and
+ * stops after a batch it cannot advance past, whereas spans have no cursor (the table is the
+ * queue) and delete a dropped chunk before continuing with the next one.
+ */
+internal enum class SpanDispatchDisposition {
+  /** Delete the chunk's rows and continue with the next chunk. */
+  DELETE_AND_CONTINUE,
+
+  /** Leave every remaining row in place and stop, so the next dispatch retries them. */
+  KEEP_AND_STOP,
+
+  /** Too large to send but still splittable: retry the halves before anything after them. */
+  HALVE_AND_RETRY
+}
+
+/**
+ * Maps a send outcome onto what the loop does next. Pure, so every branch is assertable without
+ * a database, a network, or a coroutine scope.
+ *
+ * @param chunkCount how many spans were in the chunk that produced [result].
+ */
+internal fun spanDispatchDisposition(result: DispatchResult, chunkCount: Int): SpanDispatchDisposition =
+  when (result) {
+    DispatchResult.Success, is DispatchResult.PartialSuccess ->
+      SpanDispatchDisposition.DELETE_AND_CONTINUE
+    is DispatchResult.RetryableFailure -> SpanDispatchDisposition.KEEP_AND_STOP
+    is DispatchResult.NonRetryableFailure -> SpanDispatchDisposition.DELETE_AND_CONTINUE
+    // A single row cannot be split, so it is dropped: keeping it would block every span behind
+    // it on every future dispatch.
+    DispatchResult.PayloadTooLarge -> if (chunkCount > 1) {
+      SpanDispatchDisposition.HALVE_AND_RETRY
+    } else {
+      SpanDispatchDisposition.DELETE_AND_CONTINUE
+    }
+  }

package/build/module.web.d.ts

@@ -17,5 +17,5 @@ declare class ExpoObserveModule extends NativeModule<ObserveModuleEvents> implem
         isJsDev: boolean;
     }): void;
 }
-declare const _default: typeof ExpoObserveModule;
+declare const _default: ExpoObserveModule;
 export default _default;

package/build/types.d.ts

@@ -162,7 +162,8 @@ export declare class ObserveModule extends NativeModule<ObserveModuleEvents> {
      * this method to flush events manually, for example, during testing or to ensure events
      * are sent before a specific point.
      *
-     * @returns A promise that resolves when the pending events have been dispatched.
+     * @returns A promise that resolves once the events have been dispatched. A call made while
+     * another dispatch is running waits for it to finish first.
      *
      * @example
      * ```ts

package/build/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["types.ts"],"sourcesContent":[null],"names":[],"mappings":"AAqIA,WAwJC"}
+{"version":3,"sources":["types.ts"],"sourcesContent":[null],"names":[],"mappings":"AAqIA,WAyJC"}

package/expo-module.config.json

@@ -9,7 +9,7 @@
     "publication": {
       "groupId": "expo.modules.observe",
       "artifactId": "expo.modules.observe",
-      "version": "58.0.0",
+      "version": "58.0.3",
       "repository": "local-maven-repo"
     }
   }

package/ios/DispatchSerializer.swift

@@ -0,0 +1,40 @@
+// Copyright 2025-present 650 Industries. All rights reserved.
+
+import ExpoAppMetrics
+
+/// Runs dispatch passes one at a time, so a later caller waits for the pass ahead of it instead
+/// of overlapping with it.
+///
+/// `ObservabilityManager` is actor-isolated but reentrant at every network `await`, so two
+/// overlapping passes would read and send the same pending rows before either advanced its cursor
+/// or deleted its batch. Serializing also lets a JS `dispatchEvents()` promise mean the queue was
+/// drained, matching Android's per-signal mutexes.
+@AppMetricsActor
+internal final class DispatchSerializer {
+  private var inFlight: Task<Void, Never>?
+  private var generation = 0
+  private var inFlightGeneration = 0
+
+  /// Waits for any pass already running, then runs `work` as the new in-flight pass.
+  internal func run(_ work: @escaping () async -> Void) async {
+    // The predecessor is captured and awaited *inside* the new task, not before creating it.
+    // Awaiting first would suspend, letting two callers both observe a finished pass and start
+    // work concurrently. Chaining publishes this task synchronously, so the next caller links
+    // behind it.
+    let predecessor = inFlight
+    generation += 1
+    let ownGeneration = generation
+    let task = Task {
+      await predecessor?.value
+      await work()
+    }
+    inFlight = task
+    inFlightGeneration = ownGeneration
+    await task.value
+    // Cleared only when still the current pass, so a caller resuming late cannot orphan the pass
+    // that replaced it.
+    if inFlightGeneration == ownGeneration {
+      inFlight = nil
+    }
+  }
+}