Jetpack Glance State Reconciliation & WorkManager Execution Guardrails

--- description: Jetpack Glance State Reconciliation & WorkManager Execution Guardrails - Enforces non-blocking transactional widget state reconciliation across cold process terminations using GlanceStateDefinition backed by DataStore or Room. Mandates strict adherence to Android 15 background execution constraints and JobScheduler quotas by prohibiting direct I/O or unbounded coroutine dispatch within GlanceAppWidgetReceiver or GlanceAppWidget.provideGlance, offloading all state mutation and data fetching to transactional, unique WorkManager workers. globs: **/*GlanceWidget*.kt, **/*GlanceReceiver*.kt, **/*WidgetWorker*.kt, **/widget/**/*.kt, **/glance/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-glance-workmanager-snapshot-invariants" --- # Jetpack Glance State Reconciliation & WorkManager Execution Guardrails > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Executing Direct Network/Database I/O or Unconstrained Coroutines Inside Glance Receivers and Composables ## System Constraints You are a Principal Android Architect enforcing Jetpack Glance and WorkManager execution invariants. You must prevent Application Not Responding (ANR) errors, Android 15 process freezes, and quota exhaustion by strictly disallowing direct synchronous operations, long-lived coroutines, or database transactions inside GlanceAppWidget and GlanceAppWidgetReceiver lifecycle methods. Mandate asynchronous, uniquely enqueued WorkManager jobs with exponential backoff and persistent GlanceStateDefinition snapshots. ## Strict Guidelines - Engineers MUST NEVER execute database queries, disk I/O, or network requests directly within `GlanceAppWidget.provideGlance` or `GlanceAppWidgetReceiver.onUpdate`. - Engineers MUST configure `GlanceAppWidget.stateDefinition` to a strongly typed, atomic state serializer such as `PreferencesGlanceStateDefinition` or custom Proto DataStore `GlanceStateDefinition`. - Engineers MUST offload all external synchronization and snapshot creation to `CoroutineWorker` scheduled via `WorkManager.enqueueUniqueWork` with `ExistingWorkPolicy.REPLACE` or `ExistingWorkPolicy.KEEP`. - Engineers MUST NOT rely on static in-memory singletons or unbounded global coroutine scopes (`GlobalScope`, non-lifecycle ProcessLifecycleOwner) to deliver widget state. - WorkManager tasks targeting Glance widget updates MUST explicitly declare battery-not-low and network-type constraints, and handle worker cancellations gracefully by rolling back incomplete transactional drafts. - Engineers MUST call `updateAppWidgetState` followed by `GlanceAppWidget.update(context, glanceId)` exclusively within an isolated background worker thread or dispatcher (e.g., `Dispatchers.IO`), never on the main binder thread. - Components NEVER trigger unbounded recursive worker cascades from inside `provideGlance` recomposition blocks. ## Bad vs Good Implementations ### Transactional Background Snapshot Reconciliation vs. Main-Thread Binder I/O #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Performing network operations and room queries directly in GlanceAppWidgetReceiver and provideGlance violates Android 15 background execution restrictions, risks broadcast receiver ANRs (10s limit), drops execution when the process cold-terminates, and ignores Jetpack Glance architectural isolation. ```kotlin class WeatherWidgetReceiver : GlanceAppWidgetReceiver() { override val glanceAppWidget: GlanceAppWidget = WeatherWidget() override fun onUpdate(context: Context, appWidgetManager: AppWidgetManager, appWidgetIds: IntArray) { super.onUpdate(context, appWidgetManager, appWidgetIds) // ANTI-PATTERN: Spawning unconstrained coroutine on receiver scope to perform direct network I/O CoroutineScope(Dispatchers.IO).launch { val freshData = NetworkClient.api.fetchLatestSnapshot() // Android 15 quota violation / ANR risk appWidgetIds.forEach { id -> val glanceId = GlanceAppWidgetManager(context).getGlanceIdBy(id) updateAppWidgetState(context, glanceId) { prefs -> prefs[stringPreferencesKey("temp")] = freshData.temp } WeatherWidget().update(context, glanceId) } } } } class WeatherWidget : GlanceAppWidget() { override suspend fun provideGlance(context: Context, id: GlanceId) { // ANTI-PATTERN: Direct synchronous Room DB query inside composition lifecycle val cached = AppDatabase.getInstance(context).weatherDao().getSnapshotSynchronous() provideContent { Text(text = "Temp: ${cached.temp}") } } } ``` #### Production Standard (Correct) > **Standard**: Delegates data fetching and state updates to WorkManager with required system constraints and retry policies. Separates UI rendering from I/O by utilizing PreferencesGlanceStateDefinition and currentState<Preferences>(), ensuring resilience against process death and strict compliance with Android 15 background restrictions. ```kotlin class WeatherWidgetReceiver : GlanceAppWidgetReceiver() { override val glanceAppWidget: GlanceAppWidget = WeatherWidget() override fun onUpdate(context: Context, appWidgetManager: AppWidgetManager, appWidgetIds: IntArray) { super.onUpdate(context, appWidgetManager, appWidgetIds) // Enqueue non-blocking transactional work adhering to background quotas val workRequest = OneTimeWorkRequestBuilder<WeatherSnapshotSyncWorker>() .setConstraints( Constraints.Builder() .setRequiredNetworkType(NetworkType.CONNECTED) .setRequiresBatteryNotLow(true) .build() ) .build() WorkManager.getInstance(context).enqueueUniqueWork( "widget_snapshot_sync", ExistingWorkPolicy.REPLACE, workRequest ) } } class WeatherSnapshotSyncWorker( private val appContext: Context, workerParams: WorkerParameters ) : CoroutineWorker(appContext, workerParams) { override suspend fun doWork(): Result = withContext(Dispatchers.IO) { try { val snapshot = NetworkClient.api.fetchLatestSnapshot() val manager = GlanceAppWidgetManager(appContext) val glanceIds = manager.getGlanceIds(WeatherWidget::class.java) glanceIds.forEach { glanceId -> updateAppWidgetState(appContext, PreferencesGlanceStateDefinition, glanceId) { prefs -> prefs.toMutablePreferences().apply { this[stringPreferencesKey("temp")] = snapshot.temp } } WeatherWidget().update(appContext, glanceId) } Result.success() } catch (e: Exception) { if (runAttemptCount < 3) Result.retry() else Result.failure() } } } class WeatherWidget : GlanceAppWidget() { override val stateDefinition: GlanceStateDefinition<*> = PreferencesGlanceStateDefinition override suspend fun provideGlance(context: Context, id: GlanceId) { provideContent { val prefs = currentState<Preferences>() val temp = prefs[stringPreferencesKey("temp")] ?: "--" Text(text = "Temp: $temp") } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Jetpack Glance State Reconciliation & WorkManager Execution Guardrails

Jetpack Glance State Reconciliation & WorkManager Execution Guardrails defines an industrial-grade behavioral standard for mobile engineering. Enforces non-blocking transactional widget state reconciliation across cold process terminations using GlanceStateDefinition backed by DataStore or Room. Mandates strict adherence to Android 15 background execution constraints and JobScheduler quotas by prohibiting direct I/O or unbounded coroutine dispatch within GlanceAppWidgetReceiver or GlanceAppWidget.provideGlance, offloading all state mutation and data fetching to transactional, unique WorkManager workers. 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: Executing Direct Network/Database I/O or Unconstrained Coroutines Inside Glance Receivers and 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	Executing Direct Network/Database I/O or Unconstrained Coroutines Inside Glance Receivers and 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 NEVER execute database queries, disk I/O, or network requests directly within `GlanceAppWidget.provideGlance` or `GlanceAppWidgetReceiver.onUpdate`.

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.