📜 Description

Serialize Session Replay lifecycle changes through the Android main looper and keep the active lifecycle, capture strategy, replay ID, and generation in one atomic state value. Every lifecycle command is queued, including calls already made from main, which preserves ordering across callers and defers replay startup beyond the SDK initialization critical path.

This removes the replay lifecycle and encoder locks that could block Android lifecycle callbacks and cause deadlocks or ANRs. Encoder work and cache cleanup remain ordered on the replay executor. Close performs main-thread teardown before executor shutdown; if a background close times out, the already-queued teardown still shuts the executors down after cleanup has been scheduled.

Event correlation remains synchronous where required. The internal ReplayController.captureReplay() contract now returns the active replay ID and sets it on the scope before deferred conversion. Terminating capture reaches the active strategy immediately so a main-thread crash cannot block it behind the looper. Deferred capture callbacks validate the replay generation, ID, and strategy before changing state, preventing an old replay from mutating a restarted one.

This is a breaking internal API change for hybrid SDKs that implement or bridge ReplayController. Returning the ID binds the triggering event or feedback to the exact sampled replay snapshot; falling back to the scope preserves an existing association when no new capture is accepted.

💡 Motivation and Context

Prepare Session Replay for public start and stop APIs without allowing calls from arbitrary threads to race, deadlock, or block Android lifecycle callbacks.

Always queuing startup also addresses the Session Replay initialization delay tracked in JAVA-656.

Refs JAVA-665
Refs JAVA-656

💚 How did you test it?

• Ran ./gradlew spotlessApply apiDump.
• Ran all Session Replay unit tests: 241 passed and 1 skipped.
• Ran the full SentryAndroidTest suite.
• Added focused coverage for lifecycle ordering, concurrent capture and stop, stale callbacks, crash termination, background-close timeouts, executor cleanup ordering, and deferred foreground initialization.

📝 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

• Update hybrid SDK bridges for the ReplayController.captureReplay() return type.
• Add the public Session Replay start and stop APIs in JAVA-325.
• Document manual replay lifecycle control in JAVA-691.