ref(android-nav3): Clarify route translator contracts

Document host callback containment and newest-first route processing for budgeted arguments.

Author: 0xadam-brown

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

@@ -6,7 +6,7 @@ import io.sentry.util.ExceptionUtils
 import java.util.IdentityHashMap
 import org.jetbrains.annotations.TestOnly
 
-/** Translates app-defined back stack entries into a list of input-ordered [Route]s. */
+/** Translates app-defined back stack entries into input-ordered [Route]s. */
 internal class RouteTranslator<T : Any>(
   private val resolvers: () -> RouteResolvers<T>,
   private val logger: ILogger,
@@ -16,7 +16,12 @@ internal class RouteTranslator<T : Any>(
     internal const val UNKNOWN_ROUTE_NAME = "/unknown"
   }
 
-  /** Translates the provided [backStackEntries] into [Route]s and returns them in input order. */
+  /**
+   * Translates the provided [backStackEntries] into [Route]s and returns them in input order.
+   *
+   * Callers should provide entries newest first so the shared argument budget preserves data for
+   * the destinations most relevant to the current navigation state.
+   */
   fun translate(backStackEntries: List<T>): List<Route> {
     val warningState = WarningState()
     val sanitizer = ArgumentSanitizer(logger, warningState)
@@ -49,6 +54,7 @@ internal class RouteTranslator<T : Any>(
       try {
         resolvers.invoke().getName(backStackEntry)
       } catch (t: Throwable) {
+        // Route name extractors are host app callbacks.
         ExceptionUtils.rethrowIfFatal(t)
         warningState.logNameExtractorFailureWarning(logger, t)
         return UNKNOWN_ROUTE_NAME
@@ -80,6 +86,7 @@ internal class RouteTranslator<T : Any>(
       try {
         resolvers.invoke().getArguments(backStackEntry) ?: return emptyMap()
       } catch (t: Throwable) {
+        // Route argument extractors are host app callbacks.
         ExceptionUtils.rethrowIfFatal(t)
         logger.log(
           WARNING,
@@ -129,6 +136,7 @@ internal class RouteTranslator<T : Any>(
         logger.log(WARNING, drop.warning)
         emptyMap()
       } catch (t: Throwable) {
+        // Extracted maps may invoke host app code while iterating or stringifying values.
         ExceptionUtils.rethrowIfFatal(t)
         logger.log(WARNING, STRUCTURE_WARNING, t)
         emptyMap()

sentry-android-navigation3/src/test/kotlin/io/sentry/compose/navigation3/RouteTranslatorTest.kt

@@ -60,6 +60,9 @@ class RouteTranslatorTest {
 
   @Test
   fun `translate preserves newer entry arguments when the shared budget overflows`() {
+    val newest = SettingsRoute("privacy")
+    val middle = ProfileRoute("123")
+    val oldest = HomeRoute()
     val sut =
       getSut(
         argumentsExtractor =
@@ -73,7 +76,7 @@ class RouteTranslatorTest {
           }
       )
 
-    val routes = sut.translate(listOf(SettingsRoute("privacy"), ProfileRoute("123"), HomeRoute()))
+    val routes = sut.translate(listOf(newest, middle, oldest))
 
     assertThat(routes).hasSize(3)
     assertThat(routes[0]).isEqualTo(Route("/SettingsRoute", mapOf("section" to "privacy")))