AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
mobilecritical PriorityID: android-15-16kb-page-alignment-invariant-android-15-16kb--825

Android 15 16KB Memory Page Alignment Native Runtime Invariant

Android 15 introduces native support for devices configured with 16KB memory page sizes instead of legacy 4KB boundaries. Native shared libraries (.so) built with default 4KB page alignments will fail ELF loading or trigger unrecoverable SIGBUS memory faults when mapped into process memory on 16KB kernels. This invariant enforces mandatory 16KB ELF alignment across all CMake/NDK toolchains and verifies uncompressed APK zip-alignment.

Prohibited Anti-Pattern: Compiling Native Libraries with Legacy 4KB ELF Alignment Leading to SIGBUS Crashes on Android 15

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Android 15 16KB Memory Page Alignment Native Runtime Invariant - Android 15 introduces native support for devices configured with 16KB memory page sizes instead of legacy 4KB boundaries. Native shared libraries (.so) built with default 4KB page alignments will fail ELF loading or trigger unrecoverable SIGBUS memory faults when mapped into process memory on 16KB kernels. This invariant enforces mandatory 16KB ELF alignment across all CMake/NDK toolchains and verifies uncompressed APK zip-alignment.
globs: **/CMakeLists.txt, **/build.gradle, **/build.gradle.kts, **/*.cmake, **/Android.mk
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/android-15-16kb-page-alignment-invariant-android-15-16kb--825"
---

# Android 15 16KB Memory Page Alignment Native Runtime Invariant

> **Severity**: CRITICAL | **Category**: mobile
> **Anti-Pattern Warning**: Compiling Native Libraries with Legacy 4KB ELF Alignment Leading to SIGBUS Crashes on Android 15

## System Constraints
You are a Principal Mobile Architect enforcing Android 15 16KB page alignment invariants across all native compilation and packaging steps. Mandate that every compiled C/C++ target explicitly configures the linker for 16KB (0x4000) max-page-size, eliminate unaligned prebuilt vendored binaries, and ensure APK packaging maintains 16KB zip alignment for memory-mapped shared libraries.

## Strict Guidelines
- Engineers MUST ALWAYS configure the native linker with '-Wl,-z,max-page-size=16384' in CMake or ndk-build when using NDK r26 or lower.
- Engineers MUST upgrade to NDK r27 or higher wherever feasible, as 16KB page alignment is enabled by default for arm64-v8a and x86_64.
- Engineers MUST NOT vendor third-party prebuilt dynamic libraries (.so) without verifying alignment via 'llvm-objdump -p <lib.so>' or 'readelf -l <lib.so>' ensuring LOAD segments have alignment >= 0x4000 (16384).
- Code SHOULD verify in Gradle that packaging configurations do not corrupt ELF segment offsets during strip, zip-alignment, or compression stages.
- Services MUST ensure CI pipeline stages run automated verification scripts using 'zipalign -c -P 16 -v 4 <apk_file>' on release artifacts.
- Components NEVER bundle unaligned native binaries using legacy APK extraction or compressed JNI libraries without testing dynamic mmap execution on 16KB emulators.

## Bad vs Good Implementations
### CMake Native Target Linker Flag Configuration

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Defaulting to legacy linker flags produces ELF binaries with 4KB (0x1000) p_align attributes. When loaded on Android 15 16KB page kernel devices, the Android dynamic linker fails with dlopen() errors or crashes instantly with SIGBUS upon unaligned page access.
```cmake
# Legacy CMake configuration defaulting to 4KB page size alignment
cmake_minimum_required(VERSION 3.22.1)
project(native_engine LANGUAGES CXX)

add_library(native_engine SHARED
    src/engine.cpp
    src/renderer.cpp
)

# Omitting max-page-size flag allows ld/lld on NDK <= r26 to emit 4KB (0x1000) alignment
target_link_libraries(native_engine
    log
    android
)
```

#### Production Standard (Correct)
> **Standard**: Passing '-Wl,-z,max-page-size=16384' forces the linker to align all LOAD segments to 16KB boundaries (0x4000). The library remains backward-compatible with 4KB devices while safely supporting 16KB page sizes on Android 15+ silicon.
```cmake
# Android 15 16KB Page Aligned CMake Configuration
cmake_minimum_required(VERSION 3.22.1)
project(native_engine LANGUAGES CXX)

add_library(native_engine SHARED
    src/engine.cpp
    src/renderer.cpp
)

# Explicitly enforce 16KB (0x4000) max-page-size across all linker invocations
target_link_options(native_engine PRIVATE
    "-Wl,-z,max-page-size=16384"
)

target_link_libraries(native_engine
    log
    android
)
```

### Android Gradle Plugin (build.gradle.kts) Packaging and Flag Propagation

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Fails to enforce 16KB page alignment globally across native subprojects and omits explicit verification that uncompressed libraries in the APK are aligned to 16KB zip entry offsets.
```kotlin
// build.gradle.kts with default legacy settings
android {
    compileSdk = 34

    defaultConfig {
        ndk {
            abiFilters.addAll(listOf("arm64-v8a", "x86_64"))
        }
    }
    // No packaging alignment safeguards or global C++ linker flags
}
```

#### Production Standard (Correct)
> **Standard**: Uses NDK r27+, passes the 16KB page size linker flags directly into external Native builds, and disables legacy JNI packaging so Android Gradle Plugin pages binaries to 16KB byte boundaries inside the uncompressed APK.
```kotlin
// build.gradle.kts enforcing 16KB alignment invariants
android {
    compileSdk = 35
    ndkVersion = "27.1.12297006" // NDK r27+ defaults to 16KB alignment

    defaultConfig {
        ndk {
            abiFilters.addAll(listOf("arm64-v8a", "x86_64"))
        }
        externalNativeBuild {
            cmake {
                arguments += "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
                cFlags += "-Wl,-z,max-page-size=16384"
                cppFlags += "-Wl,-z,max-page-size=16384"
            }
        }
    }

    packaging {
        jniLibs {
            // Keep uncompressed so dynamic linker mmaps directly with 16KB alignment
            useLegacyPackaging = false
        }
    }
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

Android Build Verification MCP
Inspects APK artifacts, ELF load headers, and runs zipalign checks automatically inside agent workflows.
Recommended Agent Skills (askills.dev)

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

Verify ELF 16KB Alignment CLI
Automated script running llvm-readelf or readelf -lW on .so libraries to assert all PT_LOAD segments have 0x4000 alignment.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 16KB Memory Page Alignment Native Runtime Invariant

Android 15 16KB Memory Page Alignment Native Runtime Invariant defines an industrial-grade behavioral standard for mobile engineering. Android 15 introduces native support for devices configured with 16KB memory page sizes instead of legacy 4KB boundaries. Native shared libraries (.so) built with default 4KB page alignments will fail ELF loading or trigger unrecoverable SIGBUS memory faults when mapped into process memory on 16KB kernels. This invariant enforces mandatory 16KB ELF alignment across all CMake/NDK toolchains and verifies uncompressed APK zip-alignment. 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: Compiling Native Libraries with Legacy 4KB ELF Alignment Leading to SIGBUS Crashes on Android 15 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftCompiling Native Libraries with Legacy 4KB ELF Alignment Leading to SIGBUS Crashes on Android 15Critical
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 InconsistencyAI 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 configure the native linker with '-Wl,-z,max-page-size=16384' in CMake or ndk-build when using NDK r26 or lower.

Engineers MUST ALWAYS configure the native linker with '-Wl,-z,max-page-size=16384' in CMake or ndk-build when using NDK r26 or lower.

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 upgrade to NDK r27 or higher wherever feasible, as 16KB page alignment is enabled by default for arm64-v8a and x86_64.

Engineers MUST upgrade to NDK r27 or higher wherever feasible, as 16KB page alignment is enabled by default for arm64-v8a and x86_64.

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 NOT vendor third-party prebuilt dynamic libraries (.so) without verifying alignment via 'llvm-objdump -p <lib.so>' or 'readelf -l <lib.so>' ensuring LOAD segments have alignment >= 0x4000 (16384).

Engineers MUST NOT vendor third-party prebuilt dynamic libraries (.so) without verifying alignment via 'llvm-objdump -p <lib.so>' or 'readelf -l <lib.so>' ensuring LOAD segments have alignment >= 0x4000 (16384).

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

Code SHOULD verify in Gradle that packaging configurations do not corrupt ELF segment offsets during strip, zip-alignment, or compression stages.

Code SHOULD verify in Gradle that packaging configurations do not corrupt ELF segment offsets during strip, zip-alignment, or compression stages.

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

Services MUST ensure CI pipeline stages run automated verification scripts using 'zipalign -c -P 16 -v 4 <apk_file>' on release artifacts.

Services MUST ensure CI pipeline stages run automated verification scripts using 'zipalign -c -P 16 -v 4 <apk_file>' on release artifacts.

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

Components NEVER bundle unaligned native binaries using legacy APK extraction or compressed JNI libraries without testing dynamic mmap execution on 16KB emulators.

Components NEVER bundle unaligned native binaries using legacy APK extraction or compressed JNI libraries without testing dynamic mmap execution on 16KB emulators.

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 16KB Memory Page Alignment Native Runtime Invariant critical for AI coding assistants?

Android 15 introduces native support for devices configured with 16KB memory page sizes instead of legacy 4KB boundaries. Native shared libraries (.so) built with default 4KB page alignments will fail ELF loading or trigger unrecoverable SIGBUS memory faults when mapped into process memory on 16KB kernels. This invariant enforces mandatory 16KB ELF alignment across all CMake/NDK toolchains and verifies uncompressed APK zip-alignment. 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 (Compiling Native Libraries with Legacy 4KB ELF Alignment Leading to SIGBUS Crashes on Android 15) 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 →
mobile
106

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.

mobile
70

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.

mobile
58

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