Android 15 ADPF Thermal Headroom and Workload Governor Protocol | AgentRules.org

Rules Stacks Clients Auditor Pruner Self-Heal RFCs Benchmark CLI CI/CD Authors Submit

This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →

mobilecritical PriorityID: adpf-thermal-workload-governor-standard

Android 15 ADPF Thermal Headroom and Workload Governor Protocol

Enforces proactive hardware thermal throttling mitigation using Android 15 ADPF APIs (PerformanceHintManager and PowerManager thermal headroom callbacks). Guarantees that render loops dynamically scale graphics fidelity, frame pacing, and worker thread affinities before the OS triggers severe DVFS downclocking or dropped frames.

Prohibited Anti-Pattern: Reactive Thermal Handling via OnThermalStatusChanged or Polling Without Target Duration Feedback

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Android 15 ADPF Thermal Headroom and Workload Governor Protocol - Enforces proactive hardware thermal throttling mitigation using Android 15 ADPF APIs (PerformanceHintManager and PowerManager thermal headroom callbacks). Guarantees that render loops dynamically scale graphics fidelity, frame pacing, and worker thread affinities before the OS triggers severe DVFS downclocking or dropped frames.
globs: **/*.kt, **/*.java, **/*.cpp, **/*.h, app/src/main/jni/**/*.{cpp,h}, app/src/main/java/**/*.kt
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/adpf-thermal-workload-governor-standard"
---

# Android 15 ADPF Thermal Headroom and Workload Governor Protocol

> **Severity**: CRITICAL | **Category**: mobile
> **Anti-Pattern Warning**: Reactive Thermal Handling via OnThermalStatusChanged or Polling Without Target Duration Feedback

## System Constraints
You are a Principal Mobile Graphics & Systems Architect enforcing Android 15 Dynamic Performance Framework (ADPF) invariants. You mandate continuous performance session feedback, forecast-aware thermal headroom scaling, and strict separation between foreground render deadlines and thermal throttling state machines.

## Strict Guidelines
- Engineers MUST ALWAYS initialize a `PerformanceHintManager.Session` targeting the active graphics pipeline threads (Choreographer/render thread and critical worker threads).
- Engineers MUST report actual frame durations via `session.reportActualWorkDuration()` at the conclusion of every single frame, matching the declared target frame deadline.
- Engineers MUST query `PowerManager.getThermalHeadroom(int forecastSeconds)` on a debounced interval (minimum 1000ms cadence) rather than relying exclusively on discrete `onThermalStatusChanged` listener states.
- Engineers MUST NOT block the UI or RenderThread while calculating thermal headroom or re-allocating pipeline fidelity tiers.
- Engines MUST gracefully downscale rendering attributes (e.g., dynamic resolution scaling, shadow cascade passes, particle counts, post-processing filters) before thermal headroom reaches `1.0`.
- When thermal headroom exceeds `0.85` or severe throttling is imminent, the governor MUST adjust target frame rate targets (e.g., drop from 120Hz/90Hz to 60Hz or 30Hz) explicitly calling `session.updateTargetWorkDuration()` with the adjusted period.
- Native C++ / NDK code MUST interface via `APerformanceHint_createSession`, `APerformanceHint_reportActualWorkDuration`, and `AThermal_getThermalHeadroom`.

## Bad vs Good Implementations
### Kotlin ADPF Session and Thermal Headroom Governor

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Relies solely on reactive OnThermalStatusChanged (which triggers after throttling has already occurred) and fails to create or update an ADPF PerformanceHintManager session, preventing the Android OS kernel scheduler from optimizing CPU/GPU frequencies proactively.
```kotlin
class BadEngineLoop(private val powerManager: PowerManager) : PowerManager.OnThermalStatusChangedListener {
    override fun onThermalStatusChanged(status: Int) {
        // ANTI-PATTERN: Reactive handling only triggers after OS throttling has already started
        if (status >= PowerManager.THERMAL_STATUS_SEVERE) {
            QualitySettings.setLowQuality()
        }
    }

    fun renderFrame(nanos: Long) {
        // ANTI-PATTERN: No feedback to ADPF PerformanceHintManager;
        // OS DVFS cannot schedule thread clusters properly.
        executeRenderWork()
    }
}
```

#### Production Standard (Correct)
> **Standard**: Implements proactive thermal headroom polling using getThermalHeadroom with a forward-looking forecast, reports exact execution durations back to the OS via PerformanceHintManager.Session on every frame, and adjusts graphics fidelity tiers before OS-level DVFS thermal throttling triggers.
```kotlin
class AdpfWorkloadGovernor(
    private val context: Context,
    private val performanceHintManager: PerformanceHintManager,
    private val powerManager: PowerManager,
    private val renderThreadTids: IntArray
) {
    private var hintSession: PerformanceHintManager.Session? = null
    private var targetWorkDurationNanos: Long = 16_666_666L // 60 FPS target
    private var lastThermalCheckNanos: Long = 0L
    private val thermalPollIntervalNanos: Long = 1_000_000_000L // 1 second

    fun initialize() {
        hintSession = performanceHintManager.createHintSession(
            renderThreadTids,
            targetWorkDurationNanos
        )
    }

    fun onFrameStart(): Long = System.nanoTime()

    fun onFrameEnd(startNanos: Long) {
        val now = System.nanoTime()
        val actualDurationNanos = now - startNanos

        // Report continuous actual duration metrics to OS scheduler
        hintSession?.reportActualWorkDuration(actualDurationNanos)

        // Periodically poll forecast headroom (Android 15 ADPF)
        if (now - lastThermalCheckNanos > thermalPollIntervalNanos) {
            lastThermalCheckNanos = now
            evaluateThermalBudget()
        }
    }

    private fun evaluateThermalBudget() {
        // Forecast 5 seconds ahead to anticipate thermal throttling
        val headroom = powerManager.getThermalHeadroom(5)
        when {
            headroom >= 0.95f -> GraphicsFidelityManager.setTier(FidelityTier.MINIMAL)
            headroom >= 0.80f -> GraphicsFidelityManager.setTier(FidelityTier.BALANCED)
            headroom < 0.60f -> GraphicsFidelityManager.setTier(FidelityTier.ULTRA)
        }
    }

    fun updateRefreshRate(targetDurationNanos: Long) {
        this.targetWorkDurationNanos = targetDurationNanos
        hintSession?.updateTargetWorkDuration(targetDurationNanos)
    }

    fun release() {
        hintSession?.close()
        hintSession = null
    }
}
```

Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Android Debug Bridge MCP

Enables querying device thermal states, dumpsys thermal services, and frame timing metrics via ADB.

Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Perfetto Android Tracing Skill

Profiles Android 15 ADPF tracepoints (adpf, sched, thermal) to verify thermal headroom reactions and CPU core affinity shifts.

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 ADPF Thermal Headroom and Workload Governor Protocol

Android 15 ADPF Thermal Headroom and Workload Governor Protocol defines an industrial-grade behavioral standard for mobile engineering. Enforces proactive hardware thermal throttling mitigation using Android 15 ADPF APIs (PerformanceHintManager and PowerManager thermal headroom callbacks). Guarantees that render loops dynamically scale graphics fidelity, frame pacing, and worker thread affinities before the OS triggers severe DVFS downclocking or dropped frames. 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: Reactive Thermal Handling via OnThermalStatusChanged or Polling Without Target Duration Feedback 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	Reactive Thermal Handling via OnThermalStatusChanged or Polling Without Target Duration Feedback	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:

1

Engineers MUST ALWAYS initialize a `PerformanceHintManager.Session` targeting the active graphics pipeline threads (Choreographer/render thread and critical worker threads).

Engineers MUST ALWAYS initialize a `PerformanceHintManager.Session` targeting the active graphics pipeline threads (Choreographer/render thread and critical worker threads).

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

2

Engineers MUST report actual frame durations via `session.reportActualWorkDuration()` at the conclusion of every single frame, matching the declared target frame deadline.

Engineers MUST report actual frame durations via `session.reportActualWorkDuration()` at the conclusion of every single frame, matching the declared target frame deadline.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

3

Engineers MUST query `PowerManager.getThermalHeadroom(int forecastSeconds)` on a debounced interval (minimum 1000ms cadence) rather than relying exclusively on discrete `onThermalStatusChanged` listener states.

Engineers MUST query `PowerManager.getThermalHeadroom(int forecastSeconds)` on a debounced interval (minimum 1000ms cadence) rather than relying exclusively on discrete `onThermalStatusChanged` listener states.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

4

Engineers MUST NOT block the UI or RenderThread while calculating thermal headroom or re-allocating pipeline fidelity tiers.

Engineers MUST NOT block the UI or RenderThread while calculating thermal headroom or re-allocating pipeline fidelity tiers.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

5

Engines MUST gracefully downscale rendering attributes (e.g., dynamic resolution scaling, shadow cascade passes, particle counts, post-processing filters) before thermal headroom reaches `1.0`.

Engines MUST gracefully downscale rendering attributes (e.g., dynamic resolution scaling, shadow cascade passes, particle counts, post-processing filters) before thermal headroom reaches `1.0`.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

6

When thermal headroom exceeds `0.85` or severe throttling is imminent, the governor MUST adjust target frame rate targets (e.g., drop from 120Hz/90Hz to 60Hz or 30Hz) explicitly calling `session.updateTargetWorkDuration()` with the adjusted period.

When thermal headroom exceeds `0.85` or severe throttling is imminent, the governor MUST adjust target frame rate targets (e.g., drop from 120Hz/90Hz to 60Hz or 30Hz) explicitly calling `session.updateTargetWorkDuration()` with the adjusted period.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

7

Native C++ / NDK code MUST interface via `APerformanceHint_createSession`, `APerformanceHint_reportActualWorkDuration`, and `AThermal_getThermalHeadroom`.

Native C++ / NDK code MUST interface via `APerformanceHint_createSession`, `APerformanceHint_reportActualWorkDuration`, and `AThermal_getThermalHeadroom`.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Android 15 ADPF Thermal Headroom and Workload Governor Protocol critical for AI coding assistants?

Enforces proactive hardware thermal throttling mitigation using Android 15 ADPF APIs (PerformanceHintManager and PowerManager thermal headroom callbacks). Guarantees that render loops dynamically scale graphics fidelity, frame pacing, and worker thread affinities before the OS triggers severe DVFS downclocking or dropped frames. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Reactive Thermal Handling via OnThermalStatusChanged or Polling Without Target Duration Feedback) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related MOBILE Rules

View all rules →

Tauri 2.0 Mobile IPC & Capabilities Permissions Matrix Standard

Tauri v2 introduces a capability-driven permissions system replacing legacy v1 allowlists across iOS and Android runtimes. Failure to constrain IPC command handlers with typed schemas and explicit mobile capability definitions exposes native mobile OS surfaces to arbitrary code execution, permission leakage, and silent serialization failures. Production mobile deployments require strictly typed IPC boundary validation, granular capability scopes, and graceful permission degradation.

Capacitor 7 Native Bridge, Biometric Auth & Android 15 Lifecycle Production Standard

Capacitor 7 enforces strict bridge lifecycle contracts, asynchronous native plugin interop, and mandatory Android 15 edge-to-edge window inset handling. Storing sensitive authentication tokens in unencrypted web storage or failing to bind biometric authentication directly to hardware-backed Keystore or Secure Enclave mechanisms compromises app integrity and causes fatal crash or viewport occlusion issues on modern mobile operating systems.

Tauri 2.0 Mobile IPC Isolation and Capabilities Permission Scoping

Enforces strict capability permission boundaries, payload validation, and secure IPC invoke scoping for Tauri v2 Android and iOS environments. Prevents arbitrary IPC command execution, excessive native privilege granting, and deserialization vulnerabilities across the mobile webview-native boundary.

1 Rule in Stack

Android