Jetpack Compose Strong Skipping Mode & Type Stability Contract

--- description: Jetpack Compose Strong Skipping Mode & Type Stability Contract - Enforces strict Compose compiler stability contracts and immutable data structures under Strong Skipping Mode to prevent structural recomposition cascades in high-framerate screens. Mandates explicit stability annotations for cross-module domain objects, replaces non-guaranteed standard collection interfaces with kotlinx.collections.immutable types, and prevents unstable lambda capture scopes. globs: **/*.kt, **/ui/**/*.kt, **/presentation/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/jetpack-compose-strong-skipping-stability-contract" --- # Jetpack Compose Strong Skipping Mode & Type Stability Contract > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Exposing Raw Collection Interfaces and Unannotated Cross-Module Domain Types to Lazy Item Composables ## System Constraints You are a Principal Android Architect enforcing Jetpack Compose runtime stability invariants. Strong Skipping Mode relies on structural equality (equals/hashCode) for unstable parameters to skip recomposition; however, standard collections (List, Set, Map) and domain entities from non-Compose Gradle modules break skipping optimizations when identity changes or structural equality evaluates slowly. Enforce strict immutability markers (@Immutable/@Stable), persistent collections, and memoized lambda closures across all Composable interfaces. ## Strict Guidelines - Engineers MUST ALWAYS annotate UI State models with @Immutable or @Stable when wrapping external domain entities or types compiled outside Compose-enabled modules. - Engineers MUST replace standard Kotlin collection interfaces (List<T>, Set<T>, Map<K,V>) in Composable signatures with kotlinx.collections.immutable types (PersistentList<T>, ImmutableList<T>) to guarantee compiler-recognized stability. - Engineers MUST NOT rely on Strong Skipping Mode fallback for objects lacking structural equality (equals/hashCode) overrides, as identity inequality will force unnecessary recompositions. - Components MUST specify explicit 'key' and 'contentType' parameters on LazyLayout items (LazyColumn, LazyRow, LazyGrid) to allow slot-table reuse and avoid layout re-instantiation. - Engineers MUST memoize callbacks inside iterating scopes (e.g., items, itemsIndexed) or pass primitive identifiers instead of allocating anonymous lambdas capturing iteration variables directly to child composables. ## Bad vs Good Implementations ### Unstable Domain DTO & Raw Collections vs Immutable Persistent UI State #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: List<T> is an interface with no stability guarantee. While Strong Skipping enables skipping based on equals(), standard collections require O(N) equality checks during recomposition. Capturing dynamic loop variables in anonymous lambdas also forces unstable child parameter comparisons. ```kotlin // Anti-Pattern: Non-annotated external domain model & standard List interface // Even with Strong Skipping Mode, List<T> is considered unstable and external models // from modules without Compose compiler break compiler optimizations. package com.example.feature.feed import androidx.compose.foundation.lazy.LazyColumn import androidx.compose.foundation.lazy.items import androidx.compose.runtime.Composable import com.example.domain.model.Transaction // External non-compose module @Composable fun TransactionFeed( transactions: List<Transaction>, onTransactionSelected: (Transaction) -> Unit ) { LazyColumn { // Missing key and contentType causes complete slot reallocation on mutations items(transactions) { tx -> // Allocates unstable lambda capturing item state every recomposition TransactionItemRow( transaction = tx, onClick = { onTransactionSelected(tx) } ) } } } ``` #### Production Standard (Correct) > **Standard**: The UI state uses @Immutable data structures and PersistentList, which are guaranteed stable by the Compose compiler. Explicit keys and contentType parameters maximize slot reuse in lazy lists, and passing callback references by ID avoids instantiating unstable lambda captures. ```kotlin // Production Fix: Explicitly marked @Immutable state with PersistentList and item keys package com.example.feature.feed import androidx.compose.foundation.lazy.LazyColumn import androidx.compose.foundation.lazy.items import androidx.compose.runtime.Composable import androidx.compose.runtime.Immutable import androidx.compose.ui.Modifier import kotlinx.collections.immutable.PersistentList @Immutable data class TransactionUiModel( val id: String, val formattedAmount: String, val timestamp: Long ) @Composable fun TransactionFeed( transactions: PersistentList<TransactionUiModel>, onTransactionSelected: (String) -> Unit, modifier: Modifier = Modifier ) { LazyColumn(modifier = modifier) { items( items = transactions, key = { item -> item.id }, contentType = { "transaction_item" } ) { TransactionItemRow( transaction = it, onItemClick = onTransactionSelected ) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Jetpack Compose Strong Skipping Mode & Type Stability Contract

Jetpack Compose Strong Skipping Mode & Type Stability Contract defines an industrial-grade behavioral standard for mobile engineering. Enforces strict Compose compiler stability contracts and immutable data structures under Strong Skipping Mode to prevent structural recomposition cascades in high-framerate screens. Mandates explicit stability annotations for cross-module domain objects, replaces non-guaranteed standard collection interfaces with kotlinx.collections.immutable types, and prevents unstable lambda capture scopes. 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: Exposing Raw Collection Interfaces and Unannotated Cross-Module Domain Types to Lazy Item Composables 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	Exposing Raw Collection Interfaces and Unannotated Cross-Module Domain Types to Lazy Item Composables	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 annotate UI State models with @Immutable or @Stable when wrapping external domain entities or types compiled outside Compose-enabled modules.

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.