Android 15 Predictive Back Gesture Navigation State Restoration Invariant

--- description: Android 15 Predictive Back Gesture Navigation State Restoration Invariant - Enforces deterministic reconciliation of Fragment view hierarchies and navigation backstack states across predictive back gesture lifecycles in Android 15 (API 35). Prevents state desynchronization, phantom backstack pops, and orphaned view properties when interactive swipe-to-back gestures are canceled or interrupted mid-progress. Mandates strict separation between transient gesture-driven visual transformations and non-reversible navigation commits. globs: app/src/main/java/**/*.kt, app/src/main/kotlin/**/*.kt, feature/**/src/main/java/**/*.kt, core/navigation/src/main/java/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-15-predictive-back-gesture-state-reconciliation" --- # Android 15 Predictive Back Gesture Navigation State Restoration Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Mutating Navigation State, Committing FragmentTransactions, or Failing to Revert View Interpolations During Canceled Predictive Back Progressions ## System Constraints You are a Principal Mobile Architect enforcing Android 15 Predictive Back Gesture invariants. You must prohibit premature state commits, irreversible side effects in progress callbacks, and unhandled gesture cancellations in Fragment and Navigation architectures. Mandate exact lifecycle matching across handleOnBackStarted, handleOnBackProgressed, handleOnBackCancelled, and handleOnBackPressed. ## Strict Guidelines - Engineers MUST ALWAYS implement OnBackPressedCallback using handleOnBackStarted, handleOnBackProgressed, handleOnBackCancelled, and handleOnBackPressed to manage four-stage gesture lifecycles. - Engineers MUST NOT execute FragmentTransaction, NavController.popBackStack(), or mutate ViewModel navigational state within handleOnBackStarted or handleOnBackProgressed. - Code MUST strictly restrict handleOnBackProgressed to pure, idempotent visual interpolations (e.g., translationX, scale, alpha) calculated directly from BackEventCompat.progress. - Code MUST restore all modified view transformation properties to their default baseline values (translationX = 0f, scale = 1f, alpha = 1f) inside handleOnBackCancelled. - Components NEVER assume handleOnBackStarted will culminate in handleOnBackPressed; all resource allocations or temporary animation locks created in started/progressed MUST be disposed cleanly in handleOnBackCancelled. - Services and ViewModels MUST NEVER register persistent database or network writes triggered directly by transient back gesture events. ## Bad vs Good Implementations ### Predictive Back Callback State Reconciliation (Kotlin) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating ViewModel domain state and triggering NavController.popBackStack() inside progress interpolation breaks predictive back invariants. If the user cancels the gesture mid-swipe, the navigation state is desynchronized, leaving the Fragment destroyed or orphaned with mutated domain state. ```kotlin class CheckoutFragment : Fragment(R.layout.fragment_checkout) { override fun onViewCreated(view: View, savedInstanceState: Bundle?) { super.onViewCreated(view, savedInstanceState) requireActivity().onBackPressedDispatcher.addCallback( viewLifecycleOwner, object : OnBackPressedCallback(true) { override fun handleOnBackPressed() { findNavController().popBackStack() } // VIOLATION: Mutating business state and committing irreversible UI changes // during progressive gesture input, with no cancellation handler. fun handleOnBackProgressed(backEvent: BackEventCompat) { view.alpha = 1f - backEvent.progress if (backEvent.progress > 0.5f) { // Catastrophic: triggers navigation commit before gesture completion viewModel.cancelOrderDraft() findNavController().popBackStack() } } } ) } } ``` #### Production Standard (Correct) > **Standard**: Adheres strictly to Android 15 predictive back invariants. Gesture progress is limited strictly to ephemeral visual interpolations. When the gesture is aborted, handleOnBackCancelled reverts visual state smoothly to initial baselines, avoiding premature navigation commits or corrupted backstacks. ```kotlin class CheckoutFragment : Fragment(R.layout.fragment_checkout) { private var _binding: FragmentCheckoutBinding? = null private val binding get() = _binding!! override fun onViewCreated(view: View, savedInstanceState: Bundle?) { super.onViewCreated(view, savedInstanceState) _binding = FragmentCheckoutBinding.bind(view) val predictiveBackCallback = object : OnBackPressedCallback(true) { override fun handleOnBackStarted(backEvent: BackEventCompat) { // Initialize transient animation state; zero navigation mutations } override fun handleOnBackProgressed(backEvent: BackEventCompat) { val progress = backEvent.progress val interpolatedScale = 1f - (progress * 0.1f) binding.rootContainer.scaleX = interpolatedScale binding.rootContainer.scaleY = interpolatedScale binding.rootContainer.alpha = 1f - (progress * 0.3f) } override fun handleOnBackPressed() { // Final deterministic navigation commit findNavController().popBackStack() } override fun handleOnBackCancelled() { // Invariant: Reset view hierarchy transformations deterministically binding.rootContainer.animate() .scaleX(1.0f) .scaleY(1.0f) .alpha(1.0f) .setDuration(150L) .start() } } requireActivity().onBackPressedDispatcher.addCallback( viewLifecycleOwner, predictiveBackCallback ) } override fun onDestroyView() { super.onDestroyView() _binding = null } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 Predictive Back Gesture Navigation State Restoration Invariant

Android 15 Predictive Back Gesture Navigation State Restoration Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic reconciliation of Fragment view hierarchies and navigation backstack states across predictive back gesture lifecycles in Android 15 (API 35). Prevents state desynchronization, phantom backstack pops, and orphaned view properties when interactive swipe-to-back gestures are canceled or interrupted mid-progress. Mandates strict separation between transient gesture-driven visual transformations and non-reversible navigation commits. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Mutating Navigation State, Committing FragmentTransactions, or Failing to Revert View Interpolations During Canceled Predictive Back Progressions Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Mutating Navigation State, Committing FragmentTransactions, or Failing to Revert View Interpolations During Canceled Predictive Back Progressions	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS implement OnBackPressedCallback using handleOnBackStarted, handleOnBackProgressed, handleOnBackCancelled, and handleOnBackPressed to manage four-stage gesture lifecycles.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.