ref(android): Give each SentryNavEffect a lease registration and a transaction handle

NavLeaseCoordinator now observes each candidate's lifecycle itself, via
register(), and publishes and unpublishes its nav state through
LeasedNavState. NavScopes folds the old NavScope into an inner class
and publishes its StagedNavData and nav transaction through a single
publisher.

Each NavScopes instance now keeps its nav transaction in a
StagedNavTransaction handle, which INavScope.startNavTransaction and
finishNavTransaction drive, rather than BackStackObserver binding and
unbinding transactions itself and the coordinator retaining them.
StagedNavTransaction alone decides whether the scope's transaction slot
is free.

No behavior change: nav transactions still start only with the nav
lease and a free slot, and an owner that regains the lease still gets
its unfinished transaction back. The integration tests are unchanged.
This prepares for deferring transactions requested without the lease.

Refs JAVA-785
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: 0xadam-brown

sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/BackStackConverter.kt

@@ -450,7 +450,7 @@ internal data class NormalizedSentryBackStackEntry(
 internal fun List<NormalizedSentryBackStackEntry>.serialize(): List<Map<String, Any?>> =
   map(NormalizedSentryBackStackEntry::serialize)
 
-/** Why host-provided arguments were unavailable in emitted navigation data. */
+/** Why host-provided arguments were unavailable in emitted nav state. */
 internal enum class ArgumentDropReason(
   val serializedValue: String,
   val exhaustsUpdateBudget: Boolean = false,

sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/BackStackEntryMapper.kt

@@ -78,7 +78,7 @@ public class SentryBackStackEntry(
  *
  * If [map] throws, returns `null`, or returns a blank [name][SentryBackStackEntry.name], Sentry
  * records the destination as "/unknown". Doing so signals that name extraction needs to be fixed
- * while avoiding misleading gaps in navigation data.
+ * while avoiding misleading gaps in nav state.
  *
  * For instance, if a user navigates from `/home -> /detail -> /settings`, but the mapper for
  * `/detail` throws, the back stack record will be `/home -> /unknown -> /settings` rather than

sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/BackStackObserver.kt

@@ -2,12 +2,9 @@ package io.sentry.compose.navigation3
 
 import io.sentry.Breadcrumb
 import io.sentry.Hint
-import io.sentry.ITransaction
 import io.sentry.SentryIntegrationPackageStorage
-import io.sentry.SentryLevel.DEBUG
 import io.sentry.SentryLevel.INFO
 import io.sentry.SentryOptions
-import io.sentry.SpanStatus
 import io.sentry.TransactionContext
 import io.sentry.TransactionOptions
 import io.sentry.compose.navigation3.BackStackConverter.RetentionPolicy
@@ -16,6 +13,7 @@ import io.sentry.compose.navigation3.PreparedChange.BackStackHasSameTop
 import io.sentry.compose.navigation3.PreparedChange.BackStackIsEmpty
 import io.sentry.compose.navigation3.lifecycle.INavScope
 import io.sentry.compose.navigation3.lifecycle.INavScopes
+import io.sentry.compose.navigation3.lifecycle.INavTransaction
 import io.sentry.compose.navigation3.lifecycle.NAVIGATION_CONTEXT_KEY
 import io.sentry.protocol.App
 import io.sentry.protocol.TransactionNameSource
@@ -59,7 +57,7 @@ internal class BackStackObserver<T : Any>(
 
   private val backStackConverter = BackStackConverter(entryMapper, scopes.options.logger)
 
-  private val navTransaction = NavTransaction(scopes)
+  private val navTransactions = NavTransactions(scopes)
   private val navBreadcrumbs = NavBreadcrumbs(scopes)
   private val navScreen = NavScreen()
   private val navContext = NavContext(scopes, options)
@@ -83,7 +81,7 @@ internal class BackStackObserver<T : Any>(
   }
 
   /**
-   * Updates Sentry nav data based on the provided [backStack].
+   * Updates Sentry nav state based on the provided [backStack].
    *
    * **Data generated**
    *
@@ -113,7 +111,7 @@ internal class BackStackObserver<T : Any>(
   }
 
   /**
-   * Clears the nav data this observer recorded.
+   * Clears the nav state this observer recorded.
    *
    * Call it when observation ends so that no stale screen, nav context, or nav transaction outlives
    * it.
@@ -194,10 +192,10 @@ internal class BackStackObserver<T : Any>(
       navBreadcrumbs.emit(fromEntry = previousTop, toEntry = currentBackStack.topEntryNormalized)
     }
 
-    navTransaction.stop(scope)
+    navTransactions.stop(scope)
 
     if (areNavigationTransactionsEnabled) {
-      navTransaction
+      navTransactions
         .start(
           scope,
           currentTop.name,
@@ -231,7 +229,7 @@ internal class BackStackObserver<T : Any>(
   }
 
   private fun tearDown(scope: INavScope) {
-    navTransaction.stop(scope)
+    navTransactions.stop(scope)
     navContext.clear(scope)
     navScreen.clear(scope)
     clearPreviousTop()
@@ -277,32 +275,22 @@ private data class BackStackData<T>(
 )
 
 /** A helper class for managing nav transactions. */
-private class NavTransaction(private val scopes: INavScopes) {
+private class NavTransactions(private val scopes: INavScopes) {
 
   private companion object {
     private const val TRANSACTION_ORIGIN = "auto.navigation.nav3"
   }
 
-  private var activeNavTransaction: ITransaction? = null
-
-  /** Starts an idle navigation transaction, or no-ops if another transaction is already active. */
+  /**
+   * Starts an idle navigation transaction, or no-ops if another transaction is already active.
+   *
+   * [Stop][stop] the current navigation transaction first. See [INavScope.startNavTransaction].
+   */
   fun start(
     scope: INavScope,
     name: String,
     arguments: Map<String, Any?>,
-  ): ITransaction? {
-    scope.clearFinishedTransaction()
-
-    if (scope.transaction != null) {
-      scopes.options.logger.log(
-        DEBUG,
-        "Nav3 transaction for route %s won't be created because another transaction is active.",
-        name,
-      )
-
-      return null
-    }
-
+  ): INavTransaction? {
     val transactionOptions =
       TransactionOptions().also {
         it.isWaitForChildren = true
@@ -314,36 +302,25 @@ private class NavTransaction(private val scopes: INavScopes) {
       }
 
     val transaction =
-      scopes.startTransaction(
+      scope.startNavTransaction(
         TransactionContext(name, TransactionNameSource.ROUTE, NAVIGATION_OP),
         transactionOptions,
-      )
+      ) ?: return null
 
-    // Not an error: INavScopes.startTransaction may decline to start a transaction by design.
-    if (transaction.isNoOp) {
-      return null
+    if (arguments.isNotEmpty()) {
+      transaction.setData("arguments", arguments)
     }
 
-    activeNavTransaction = transaction
-
-    transaction.apply {
-      if (arguments.isNotEmpty()) {
-        setData("arguments", arguments)
-      }
-    }
-
-    scope.bindTransaction(transaction)
-
     return transaction
   }
 
-  /** Finishes and unsets the active navigation transaction, if one exists. */
+  /**
+   * Finishes and unsets the active navigation transaction, if one exists.
+   *
+   * See [INavScope.finishNavTransaction].
+   */
   fun stop(scope: INavScope) {
-    val transaction = activeNavTransaction ?: return
-    val status = transaction.status ?: SpanStatus.OK
-    transaction.finish(status)
-    scope.unbindTransaction(transaction)
-    activeNavTransaction = null
+    scope.finishNavTransaction()
   }
 }
 
@@ -377,15 +354,15 @@ private class NavContext(private val scopes: INavScopes, private val options: Se
    * proper values to the transaction context instead.
    */
   fun <T : Any> updateTransaction(
-    transaction: ITransaction,
+    transaction: INavTransaction,
     scope: INavScope,
     backStack: BackStackData<T>,
   ) {
     if (scopes.options.isEnableScreenTracking) {
-      val appContext = transaction.contexts.app ?: scope.app ?: App()
+      val appContext = scope.app ?: App()
 
       appContext.viewNames = listOf(backStack.topEntryNormalized.name)
-      transaction.contexts.setApp(appContext)
+      transaction.setApp(appContext)
     }
 
     if (options.captureBackStack && backStack.capturedEntriesNormalized.isNotEmpty()) {

sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/CoordinatedBackStackObserver.kt

@@ -22,7 +22,8 @@ import io.sentry.compose.navigation3.lifecycle.NavScopes
  * **Thread safety**
  *
  * This class is ***not*** thread-safe. Invocations should be confined to the same thread as the
- * [LifecycleEventObserver] callbacks implemented by [NavScopes].
+ * [LifecycleEventObserver] callbacks through which the [NavLeaseCoordinator] observes the attached
+ * lifecycle.
  */
 internal class CoordinatedBackStackObserver<T : Any>(
   scopes: IScopes,