Decoupling Predictive Back Speculative Rendering from Jetpack Compose Navigation Commits

--- description: Decoupling Predictive Back Speculative Rendering from Jetpack Compose Navigation Commits - Enforces deterministic separation between Android 15 Predictive Back speculative gesture progress animations and architectural backstack state transitions in Jetpack Compose. Prevents UI state desynchronization, ghost view states, and frame drops caused by mutating navigation state during uncommitted or cancelled back gestures. globs: app/src/main/**/*.kt, feature/**/src/main/**/*.kt, core/navigation/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-15-predictive-back-compose-navigation-invariant" --- # Decoupling Predictive Back Speculative Rendering from Jetpack Compose Navigation Commits > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Mutating Backstack or Screen ViewModel State on Predictive Back Gesture Progress Events ## System Constraints You are a Principal Android Architect enforcing strict invariants for Android 15 predictive back navigation in Jetpack Compose. You must strictly forbid any side effects, state mutations, analytics emissions, or NavHostController mutations triggered during the progress/cancellation phases of predictive back gestures. Navigation operations and business state changes must only execute upon confirmed gesture completion. ## Strict Guidelines - Engineers MUST ALWAYS isolate predictive back progress interpolation to pure visual transformations (such as GraphicsLayer scope modifiers) without triggering recomposition loops or mutating state holder properties. - Engineers MUST NOT execute `NavController.popBackStack()`, mutate `ViewModel` state, or persist draft data inside the progress phase of a `PredictiveBackHandler`. - Custom predictive back flows MUST explicitly handle cancellation via cooperative coroutine cancellation (such as catch blocks or cancellation blocks in collect) without leaving the UI in an intermediate or corrupted state. - Navigation graphs MUST utilize Compose Navigation 2.8+ built-in predictive back integration via `NavHost` rather than wrapping entire destinations in custom, intercepting `BackHandler` hooks unless providing custom interactive morphing transitions. - Components NEVER trigger I/O operations, network dispatches, or emit irreversible domain analytics events until the back gesture reaches completion (`onBack` / completion block). ## Bad vs Good Implementations ### Predictive Back Invariant: Isolating Visual Interpolation from Backstack State Mutation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating screen ViewModel state and invoking `popBackStack` based on speculative swipe progress (`progress > 0.8f`) desynchronizes the backstack. If the user cancels the gesture mid-swipe, the navigation stack may have already popped or the state corrupted, leading to blank screens, layout thrashing, and memory leaks. ```kotlin @Composable fun ProfileEditScreen( viewModel: ProfileViewModel, navController: NavController ) { // BAD: Mutating architectural/domain state on speculative progress and navigating prematurely PredictiveBackHandler(enabled = true) { progressFlow -> try { progressFlow.collect { backEvent -> // Anti-pattern: Modifying state during speculative back gesture viewModel.updateDraftProgress(backEvent.progress) if (backEvent.progress > 0.8f) { // Race condition: Pop initiated prior to actual gesture commitment navController.popBackStack() } } viewModel.discardChanges() } catch (e: CancellationException) { // State left corrupted if cancelled viewModel.resetDraft() } } ProfileContent(viewModel) } ``` #### Production Standard (Correct) > **Standard**: Pure visual transforms run via `graphicsLayer` without mutating ViewModel state. State mutation and the navigation callback `onNavigateBack()` are invoked strictly after `progressFlow` collection successfully completes. If cancelled, the coroutine throws `CancellationException`, which cleanly resets transient render state without architectural side effects. ```kotlin @Composable fun ProfileEditScreen( viewModel: ProfileViewModel, onNavigateBack: () -> Unit ) { // GOOD: Visual interpolation strictly decoupled from navigation commit var backProgress by remember { mutableFloatStateOf(0f) } PredictiveBackHandler(enabled = true) { progressFlow -> try { progressFlow.collect { backEvent -> // Safe: Update strictly local transient render scalar backProgress = backEvent.progress } // Gesture successfully committed by the user viewModel.persistOrDiscard() onNavigateBack() } catch (cancellation: CancellationException) { // Safe: Gesture was cancelled by user; revert visual scale only backProgress = 0f throw cancellation } } Box( modifier = Modifier .graphicsLayer { val scale = 1f - (backProgress * 0.1f) scaleX = scale scaleY = scale alpha = 1f - (backProgress * 0.2f) } ) { ProfileContent(viewModel) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Decoupling Predictive Back Speculative Rendering from Jetpack Compose Navigation Commits

Decoupling Predictive Back Speculative Rendering from Jetpack Compose Navigation Commits defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic separation between Android 15 Predictive Back speculative gesture progress animations and architectural backstack state transitions in Jetpack Compose. Prevents UI state desynchronization, ghost view states, and frame drops caused by mutating navigation state during uncommitted or cancelled back gestures. 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 Backstack or Screen ViewModel State on Predictive Back Gesture Progress Events 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 Backstack or Screen ViewModel State on Predictive Back Gesture Progress Events	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 isolate predictive back progress interpolation to pure visual transformations (such as GraphicsLayer scope modifiers) without triggering recomposition loops or mutating state holder properties.

Engineers MUST ALWAYS isolate predictive back progress interpolation to pure visual transformations (such as GraphicsLayer scope modifiers) without triggering recomposition loops or mutating state holder properties.

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.