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-ndk

Android 15 16KB Page Size NDK Binary Alignment Invariant

Mandates that all native C/C++ shared libraries (.so) compiled via NDK, CMake, or bundled as prebuilts enforce strict 16KB (16384 bytes) ELF segment alignment. Failure to pass 16KB max-page-size linker flags causes immediate dlopen() aborts and unrecoverable runtime crashes on Android 15 devices running with 16KB kernel configurations.

Prohibited Anti-Pattern: Packaging 4KB-Aligned Native Libraries on 16KB Page-Size Android Kernels

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Android 15 16KB Page Size NDK Binary Alignment Invariant - Mandates that all native C/C++ shared libraries (.so) compiled via NDK, CMake, or bundled as prebuilts enforce strict 16KB (16384 bytes) ELF segment alignment. Failure to pass 16KB max-page-size linker flags causes immediate dlopen() aborts and unrecoverable runtime crashes on Android 15 devices running with 16KB kernel configurations.
globs: **/CMakeLists.txt, **/build.gradle.kts, **/build.gradle, **/Android.mk, **/Application.mk
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/android-15-16kb-page-alignment-ndk"
---

# Android 15 16KB Page Size NDK Binary Alignment Invariant

> **Severity**: CRITICAL | **Category**: mobile
> **Anti-Pattern Warning**: Packaging 4KB-Aligned Native Libraries on 16KB Page-Size Android Kernels

## System Constraints
You are a Principal Mobile Systems Architect enforcing the Android 15 16KB Page Size NDK Binary Alignment Invariant. You must reject any native build configuration or vendored shared library that does not explicitly enforce 16KB ELF alignment. Android 15 supports 16KB physical memory page sizes; loading a 4KB-aligned ELF shared object triggers an instant loader fault. Enforce 16KB linker flags (-Wl,-z,max-page-size=16384), NDK r27+ upgrades, and automated CI verification using readelf across all ABI targets.

## Strict Guidelines
- Engineers MUST ALWAYS supply '-Wl,-z,max-page-size=16384' to native linker flags in CMakeLists.txt and Android.mk when compiling with NDK r26 or lower.
- Engineers MUST upgrade projects to NDK r27 (or higher) and Android Gradle Plugin 8.5.1+ where 16KB alignment is the default compiler behavior.
- Engineers MUST NOT vendor legacy prebuilt .so binaries without validating that LOAD segment alignments are set to 0x4000 (16384 bytes).
- CI/CD pipelines MUST execute ELF segment verification via 'readelf -lW <lib.so>' to assert all LOAD segment alignment fields equal 16384 (0x4000).
- Native build files MUST NEVER omit explicit 16KB page size targeting while targeting Android API level 35 (VanillaIceCream) or higher.

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

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Omitting explicit linker max-page-size flags results in 4096-byte (4KB) ELF segment alignment on NDK versions prior to r27, causing dynamic link failure and immediate termination on 16KB-paged Android 15 kernels.
```cmake
# CMakeLists.txt: Omits explicit page size flag; defaults to 4KB on legacy NDK toolchains
cmake_minimum_required(VERSION 3.22.1)
project("native_engine")

add_library(native_engine SHARED native_engine.cpp)
target_link_libraries(native_engine log)
```

#### Production Standard (Correct)
> **Standard**: Explicitly passing '-Wl,-z,max-page-size=16384' guarantees that all PT_LOAD ELF segments are aligned to 16KB boundaries, ensuring compatibility with both 4KB and 16KB page size devices.
```cmake
# CMakeLists.txt: Explicitly enforces 16KB ELF segment alignment across all NDK versions
cmake_minimum_required(VERSION 3.22.1)
project("native_engine")

add_library(native_engine SHARED native_engine.cpp)

# Enforce 16KB ELF segment alignment required by Android 15
target_link_options(native_engine PRIVATE "-Wl,-z,max-page-size=16384")
target_link_libraries(native_engine log)
```

### Gradle Build Configuration & Prebuilt Verification

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Using NDK 25 without passing max-page-size linker arguments will generate 4KB-aligned shared objects that crash when loaded on 16KB Android 15 devices.
```kotlin
// build.gradle.kts: Default external native build configuration targeting outdated NDK without flags
android {
    compileSdk = 35
    ndkVersion = "25.2.9519653"

    defaultConfig {
        externalNativeBuild {
            cmake {
                cppFlags("-std=c++17")
            }
        }
    }
}
```

#### Production Standard (Correct)
> **Standard**: Using NDK r27+ with ANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON ensures that shared libraries automatically conform to the 16KB page boundary standard without breaking 4KB backwards compatibility.
```kotlin
// build.gradle.kts: Upgraded NDK with explicit 16KB alignment flags for both compilation and prebuilts
android {
    compileSdk = 35
    // NDK r27+ enables 16KB alignment by default, or explicitly configure via arguments
    ndkVersion = "27.1.12297006"

    defaultConfig {
        externalNativeBuild {
            cmake {
                cppFlags("-std=c++17")
                arguments("-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON")
            }
        }
        ndk {
            abiFilters.addAll(listOf("arm64-v8a", "x86_64"))
        }
    }
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

Android Build & Toolchain MCP
Analyzes Gradle configurations, NDK versions, and builds APK artifacts within safe sandboxes.
Recommended Agent Skills (askills.dev)

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

ELF Page Size Alignment Verifier
Executes readelf and objdump to check PT_LOAD segment alignment on native .so libraries for Android 16KB readiness.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 16KB Page Size NDK Binary Alignment Invariant

Android 15 16KB Page Size NDK Binary Alignment Invariant defines an industrial-grade behavioral standard for mobile engineering. Mandates that all native C/C++ shared libraries (.so) compiled via NDK, CMake, or bundled as prebuilts enforce strict 16KB (16384 bytes) ELF segment alignment. Failure to pass 16KB max-page-size linker flags causes immediate dlopen() aborts and unrecoverable runtime crashes on Android 15 devices running with 16KB kernel configurations. 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: Packaging 4KB-Aligned Native Libraries on 16KB Page-Size Android Kernels 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 DriftPackaging 4KB-Aligned Native Libraries on 16KB Page-Size Android KernelsCritical
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 supply '-Wl,-z,max-page-size=16384' to native linker flags in CMakeLists.txt and Android.mk when compiling with NDK r26 or lower.

Engineers MUST ALWAYS supply '-Wl,-z,max-page-size=16384' to native linker flags in CMakeLists.txt and Android.mk when compiling with 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 projects to NDK r27 (or higher) and Android Gradle Plugin 8.5.1+ where 16KB alignment is the default compiler behavior.

Engineers MUST upgrade projects to NDK r27 (or higher) and Android Gradle Plugin 8.5.1+ where 16KB alignment is the default compiler behavior.

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 legacy prebuilt .so binaries without validating that LOAD segment alignments are set to 0x4000 (16384 bytes).

Engineers MUST NOT vendor legacy prebuilt .so binaries without validating that LOAD segment alignments are set to 0x4000 (16384 bytes).

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

CI/CD pipelines MUST execute ELF segment verification via 'readelf -lW <lib.so>' to assert all LOAD segment alignment fields equal 16384 (0x4000).

CI/CD pipelines MUST execute ELF segment verification via 'readelf -lW <lib.so>' to assert all LOAD segment alignment fields equal 16384 (0x4000).

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

Native build files MUST NEVER omit explicit 16KB page size targeting while targeting Android API level 35 (VanillaIceCream) or higher.

Native build files MUST NEVER omit explicit 16KB page size targeting while targeting Android API level 35 (VanillaIceCream) or higher.

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 Page Size NDK Binary Alignment Invariant critical for AI coding assistants?

Mandates that all native C/C++ shared libraries (.so) compiled via NDK, CMake, or bundled as prebuilts enforce strict 16KB (16384 bytes) ELF segment alignment. Failure to pass 16KB max-page-size linker flags causes immediate dlopen() aborts and unrecoverable runtime crashes on Android 15 devices running with 16KB kernel configurations. 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 (Packaging 4KB-Aligned Native Libraries on 16KB Page-Size Android Kernels) 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