ref(android): [Nav3 Lifecycle 2] Add lease-aware NavScopes facade by 0xadam-brown · Pull Request #6304 · getsentry/sentry-java

0xadam-brown · 2026-10-20T14:59:51Z

PR Stack (Nav3 Lifecycle)

📜 Description

Add a lease-aware NavScopes façade that lets us swizzle nav data writes and reads between:

the globally shared IScope, vs
an unshared StagedNavData object, specific to each NavScopes instance.

See the NavScopes KDoc for (lots) more info, including a helpful diagram of how lease handoff works.

💡 Motivation and Context

Multiple active navigation roots write to the same Sentry scope. Staging slot-based state prevents an inactive root from overwriting the currently selected root while preserving its latest state for later restoration.

addresses: JAVA-785

💚 How did you test it?

Unit tests
Integration tests (included in a later PR)
New Nav3 sample app flows (also in a later PR) + having my clanker perform lots of thorough manual testing

📝 Checklist

I added GH Issue ID & Linear ID
I added tests to verify the changes.
No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
I updated the docs if needed.
I updated the wizard if needed.
Review from the native team if needed.
No breaking change or entry added to the changelog.
No breaking change for hybrid SDKs or communicated to hybrid SDKs.
Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.

🔮 Next steps

The next PR wires this scope layer into SentryNavEffect and enables the user-facing behavior.

#skip-changelog

⚠️ Merge this PR using a merge commit (not squash). Only the collection branch is squash-merged into main.

linear-code · 2026-10-20T14:59:59Z

JAVA-274

sentry · 2026-10-20T15:03:00Z

📲 Install Builds

Android

🔗 App Name	App ID	Version	Configuration
SDK Size	io.sentry.tests.size	8.61.0 (1)	release

⚙️ sentry-android Build Distribution Settings

cursor

Stale Bugbot comment from a previous run.

Stage navigation scope state for inactive roots and publish it when the root acquires the lifecycle lease. Refs JAVA-274

The member read as a cheap accessor, which invites call sites that run more often than once per navigation. It isn't: App's copy constructor isn't public, so an App can't be copied on its own, and NavScope goes through Contexts instead. That deep-copies every context on the scope -- on Android including a fully populated Device -- and discards all of it but the App. Document the caller-facing warning on INavScope.app and the mechanism behind it on NavScope.app, so the constraint sits where it is true and whoever replaces the copy later doesn't have to re-derive it. Also records why a copy is needed at all, which was undocumented: callers mutate the result before binding it to a transaction, so handing out the scope's live App would corrupt shared scope state.

NavScope.app returned `Contexts(delegate.contexts).app`. Because App's copy constructor wasn't public, an App couldn't be copied on its own, so the only way to get one was to copy the entire Contexts and throw the rest away. That deep-copies App, Browser, Device, OperatingSystem, SentryRuntime, Feedback, Gpu, SpanContext, ProfileContext, Response, Spring and ArtContext -- on Android a Device alone is 36 fields plus an archs array clone and a TimeZone.clone() -- to keep one of the twelve. It runs once per navigation that changes the top of the back stack, whenever screen tracking is on. Make App's copy constructor public and copy the App directly. Contexts's own copy constructor already produces its App with `new App((App) value)`, the same constructor this now calls, so the returned App is built exactly as before and only the discarded work goes away. Public copy constructors are already the convention for Contexts, Response, Request, Feedback and Geo, so this doesn't introduce a new API shape. The copy is still a copy: callers mutate the result before binding it to a transaction, and handing out the scope's live App would corrupt shared scope state. The interface KDoc keeps that constraint and drops the warning about the member being expensive, which no longer holds. Tests: NavScopeTest had no coverage of `app` at all. It now pins that the result is a distinct instance carrying every field, that mutating it leaves the scope untouched, that reading it is independent of the nav lease, that it is null when the scope has no app context, and that it leaves the scope's other contexts alone. AppTest's existing clone test predates splitApks and splitNames, so those are covered now too, including splitNames being shared rather than copied -- recorded as today's behavior, not as a guarantee.

unbindTransaction cleared the scope before telling the coordinator to stop retaining the transaction. Scope.clearTransaction notifies the host app's scope observers in an unguarded loop, so one of them can throw and skip the coordinator call, leaving a retired transaction retained. Regaining the lease would then rebind it, attaching the new destination's spans to a transaction for a destination the user had already left. Tell the coordinator first. releaseTransaction runs no host app code and cannot throw, and nothing in the unbind depends on it having run. Add regression coverage for a scope observer throwing during the unbind. Refs JAVA-274 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6d8b5ae. Configure here.}

cursor · 2026-10-22T08:32:57Z

  public App() {}

-  App(final @NotNull App app) {
+  public App(final @NotNull App app) {


App copy constructor shallow-copies splitNames unlike other collections

Low Severity

The App copy constructor defensively copies permissions via newConcurrentHashMap, viewNames via newArrayList, and unknown via newConcurrentHashMap, but assigns splitNames by direct reference. The PR makes this constructor public and relies on it in NavScope.app specifically to prevent callers from mutating the scope's live App. In-place mutation of the copy's splitNames would write through to the original, undermining the isolation guarantee. The new test pins this as known behavior but doesn't fix it.

^{Reviewed by Cursor Bugbot for commit 6d8b5ae. Configure here.}

cursor · 2026-10-22T08:32:58Z

  public App() {}

-  App(final @NotNull App app) {
+  public App(final @NotNull App app) {


Newly public App copy constructor lacks @ApiStatus.Internal

Low Severity

The App(App) copy constructor is changed from package-private to public for cross-module use by NavScope.app in the sentry-android-navigation3 module. Since this is not intended as user-facing API and other protocol classes (Device, Browser, etc.) keep their copy constructors package-private, this likely needs @ApiStatus.Internal to signal it's not part of the stable public API surface.

^{Triggered by project rule: PR Review Guidelines for Cursor Bugbot}

^{Reviewed by Cursor Bugbot for commit 6d8b5ae. Configure here.}

This was referenced Oct 20, 2026

feat(android): Nav3 support for multi-Activity and multi-Fragment applications #6301

Open

ref(android): [Nav3 Lifecycle 1] Add NavLeaseCoordinator #6302

Merged

0xadam-brown marked this pull request as ready for review October 20, 2026 15:30

0xadam-brown requested review from adinauer, markushi, romtsn and runningcode as code owners October 20, 2026 15:30

0xadam-brown added the sanity-check PR needs a lightweight review for obvious issues label Oct 20, 2026

0xadam-brown changed the title ~~ref(android): [Nav3 Lifecycle 2] Add lease-aware navigation scopes~~ ref(android): [Nav3 Lifecycle 2] Add lease-aware NavScopes facade Oct 20, 2026

0xadam-brown force-pushed the feat/part-2-sentry-nav-effect-lifecycle branch from 5c8e9cf to d4b69f1 Compare October 21, 2026 11:27

0xadam-brown force-pushed the feat/part-1-sentry-nav-effect-lifecycle branch from 8292382 to a010c9e Compare October 21, 2026 11:27

cursor Bot reviewed Oct 21, 2026

View reviewed changes

Comment thread sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/lifecycle/NavScope.kt

0xadam-brown mentioned this pull request Oct 21, 2026

Support use of SentryNavEffect in multi-Activity and multi-Fragment applications #6345

Open

Base automatically changed from feat/part-1-sentry-nav-effect-lifecycle to feat/sentry-nav-effect-lifecycle October 22, 2026 07:49

0xadam-brown and others added 4 commits October 22, 2026 10:19

ref(android): [Nav3 Lifecycle 2] Add lease-aware navigation scopes

23b6ced

Stage navigation scope state for inactive roots and publish it when the root acquires the lifecycle lease. Refs JAVA-274

0xadam-brown force-pushed the feat/part-2-sentry-nav-effect-lifecycle branch from 3eac685 to 6d8b5ae Compare October 22, 2026 08:25

cursor Bot reviewed Oct 22, 2026

View reviewed changes

Navigation Menu

Repository navigation

ref(android): [Nav3 Lifecycle 2] Add lease-aware NavScopes facade - #6304

ref(android): [Nav3 Lifecycle 2] Add lease-aware NavScopes facade#6304
0xadam-brown wants to merge 4 commits into
feat/sentry-nav-effect-lifecyclefrom
feat/part-2-sentry-nav-effect-lifecycle

0xadam-brown commented Oct 20, 2026 •

edited

Loading

Uh oh!

linear-code Bot commented Oct 20, 2026

Uh oh!

sentry Bot commented Oct 20, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Oct 22, 2026

Uh oh!

cursor Bot Oct 22, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

0xadam-brown commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Stack (Nav3 Lifecycle)

📜 Description

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

🔮 Next steps

Uh oh!

linear-code Bot commented Oct 20, 2026

Uh oh!

sentry Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📲 Install Builds

Android

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Oct 22, 2026

Choose a reason for hiding this comment

App copy constructor shallow-copies splitNames unlike other collections

Uh oh!

cursor Bot Oct 22, 2026

Choose a reason for hiding this comment

Newly public App copy constructor lacks @ApiStatus.Internal

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

0xadam-brown commented Oct 20, 2026 •

edited

Loading

sentry Bot commented Oct 20, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading

App copy constructor shallow-copies `splitNames` unlike other collections

Newly public `App` copy constructor lacks `@ApiStatus.Internal`